@banzhe/dsh-devcontainer 0.2.1 → 0.3.1
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 +33 -0
- package/README.zh-CN.md +33 -0
- package/lib/client.js +151 -10
- package/lib/client.js.map +1 -1
- package/lib/{exec-CKAAz2zz.js → exec-Bcojrag9.js} +5 -4
- package/lib/exec-Bcojrag9.js.map +1 -0
- package/lib/fs.d.ts +62 -16
- package/lib/fs.d.ts.map +1 -1
- package/lib/fs.js +256 -68
- package/lib/fs.js.map +1 -1
- package/lib/helper/main.mjs +22 -3
- package/lib/index.d.ts +19 -3
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +50 -4
- package/lib/index.js.map +1 -1
- package/lib/{sbx-1GsFjQBk.js → sbx-Blgjzzoe.js} +918 -135
- package/lib/sbx-Blgjzzoe.js.map +1 -0
- package/lib/shell.d.ts +3 -3
- package/lib/shell.d.ts.map +1 -1
- package/lib/shell.js +11 -4
- package/lib/shell.js.map +1 -1
- package/lib/{types-DsF9Hz5P.d.ts → types-B2cQmBTx.d.ts} +4 -2
- package/lib/types-B2cQmBTx.d.ts.map +1 -0
- package/package.json +36 -29
- package/lib/exec-CKAAz2zz.js.map +0 -1
- package/lib/sbx-1GsFjQBk.js.map +0 -1
- package/lib/types-DsF9Hz5P.d.ts.map +0 -1
|
@@ -1,77 +1,10 @@
|
|
|
1
1
|
import z from "@deepseek-ai/schemastery";
|
|
2
|
+
import { access } from "node:fs/promises";
|
|
2
3
|
import { posix, win32 } from "node:path";
|
|
4
|
+
import { resolveAgentsHome, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
|
|
3
5
|
import { DSH_ENV_PREFIX } from "@deepseek-ai/dsh-shell";
|
|
4
6
|
import { readFileSync, statSync } from "node:fs";
|
|
5
7
|
import { createHash } from "node:crypto";
|
|
6
|
-
//#region src/options.ts
|
|
7
|
-
/**
|
|
8
|
-
* The configuration fields every row of this Bundle shares. The three rows are
|
|
9
|
-
* separate Cordis plugins (one service each), and a repository's own file may
|
|
10
|
-
* override each of these per repository — the row's value is only the default
|
|
11
|
-
* discovery applies.
|
|
12
|
-
* @module @banzhe/dsh-devcontainer/options
|
|
13
|
-
*/
|
|
14
|
-
/** Defaults for {@link ContainerOptions}. */
|
|
15
|
-
const CONTAINER_OPTION_DEFAULTS = {
|
|
16
|
-
shell: "/bin/bash",
|
|
17
|
-
cli: "auto",
|
|
18
|
-
ensureUp: true,
|
|
19
|
-
containerTimeoutMs: 3e5,
|
|
20
|
-
requireContainer: false
|
|
21
|
-
};
|
|
22
|
-
/**
|
|
23
|
-
* Apply {@link CONTAINER_OPTION_DEFAULTS} to a possibly-partial configuration, so
|
|
24
|
-
* a programmatic `apply()` behaves like a Loader row whose schema already filled
|
|
25
|
-
* the defaults in.
|
|
26
|
-
* @param config - the row's configuration, or nothing.
|
|
27
|
-
* @returns the complete container options.
|
|
28
|
-
*/
|
|
29
|
-
function containerOptions(config = {}) {
|
|
30
|
-
return {
|
|
31
|
-
shell: config.shell ?? CONTAINER_OPTION_DEFAULTS.shell,
|
|
32
|
-
cli: config.cli ?? CONTAINER_OPTION_DEFAULTS.cli,
|
|
33
|
-
ensureUp: config.ensureUp ?? CONTAINER_OPTION_DEFAULTS.ensureUp,
|
|
34
|
-
containerTimeoutMs: config.containerTimeoutMs ?? CONTAINER_OPTION_DEFAULTS.containerTimeoutMs,
|
|
35
|
-
requireContainer: config.requireContainer ?? CONTAINER_OPTION_DEFAULTS.requireContainer
|
|
36
|
-
};
|
|
37
|
-
}
|
|
38
|
-
/**
|
|
39
|
-
* The shared Schemastery fields, spread into each row's `Config` so the three
|
|
40
|
-
* rows cannot drift apart. `cli` is `auto`: an explicit container wins, the
|
|
41
|
-
* running-container label lookup comes next, and the Dev Container CLI is the
|
|
42
|
-
* fallback that can start the container. `sbx` selects the Docker Sandbox
|
|
43
|
-
* driver, which mounts the host workspace instead of reading a declaration.
|
|
44
|
-
* @returns schemastery fields for {@link ContainerOptions}.
|
|
45
|
-
*/
|
|
46
|
-
function containerOptionFields() {
|
|
47
|
-
return {
|
|
48
|
-
shell: z.string().default(CONTAINER_OPTION_DEFAULTS.shell),
|
|
49
|
-
cli: z.union([
|
|
50
|
-
"auto",
|
|
51
|
-
"devcontainer",
|
|
52
|
-
"docker",
|
|
53
|
-
"sbx"
|
|
54
|
-
]).default(CONTAINER_OPTION_DEFAULTS.cli),
|
|
55
|
-
ensureUp: z.boolean().default(CONTAINER_OPTION_DEFAULTS.ensureUp),
|
|
56
|
-
containerTimeoutMs: z.number().default(CONTAINER_OPTION_DEFAULTS.containerTimeoutMs),
|
|
57
|
-
requireContainer: z.boolean().default(CONTAINER_OPTION_DEFAULTS.requireContainer)
|
|
58
|
-
};
|
|
59
|
-
}
|
|
60
|
-
/**
|
|
61
|
-
* The two preset-source fields as the Loader validates them.
|
|
62
|
-
*
|
|
63
|
-
* They are `volatile`, so a settings write lands in the live reference the Host
|
|
64
|
-
* row reads on its next sync instead of needing a reload, and they are defaults
|
|
65
|
-
* of the Host row only: the shell and filesystem rows have no preset set.
|
|
66
|
-
* @returns schemastery fields for {@link PresetSourceOptions}.
|
|
67
|
-
*/
|
|
68
|
-
function presetSourceFields() {
|
|
69
|
-
return {
|
|
70
|
-
sources: z.array(z.string()).default([]).volatile(),
|
|
71
|
-
sbxSources: z.array(z.string()).default([]).volatile()
|
|
72
|
-
};
|
|
73
|
-
}
|
|
74
|
-
//#endregion
|
|
75
8
|
//#region src/paths.ts
|
|
76
9
|
/**
|
|
77
10
|
* Two-way translation between the host workspace path a session carries and the
|
|
@@ -136,16 +69,23 @@ function defaultContainerWorkspaceFolder(hostRoot) {
|
|
|
136
69
|
}
|
|
137
70
|
/**
|
|
138
71
|
* Match a path against a container mount point.
|
|
72
|
+
*
|
|
73
|
+
* A Windows drive path reaches a sandbox as a lowercase drive segment and a caller
|
|
74
|
+
* may write it either way, so a fold belongs to the comparison only: the answer is
|
|
75
|
+
* always sliced from the candidate, never from the mount point.
|
|
139
76
|
* @param path - candidate path, in either separator style.
|
|
140
77
|
* @param folder - the container mount point.
|
|
78
|
+
* @param options - whether to fold case while comparing.
|
|
141
79
|
* @returns the POSIX remainder (`''` for the mount point itself), or undefined when the path is elsewhere.
|
|
142
80
|
*/
|
|
143
|
-
function containerRemainder(path, folder) {
|
|
81
|
+
function containerRemainder(path, folder, options = {}) {
|
|
144
82
|
const normalized = posix.normalize(toPosixSlashes(path));
|
|
145
83
|
const root = posix.normalize(toPosixSlashes(folder));
|
|
146
|
-
|
|
147
|
-
const
|
|
148
|
-
|
|
84
|
+
const left = options.fold === true ? normalized.toLowerCase() : normalized;
|
|
85
|
+
const right = options.fold === true ? root.toLowerCase() : root;
|
|
86
|
+
if (left === right) return "";
|
|
87
|
+
const prefix = right.endsWith("/") ? right : `${right}/`;
|
|
88
|
+
return left.startsWith(prefix) ? normalized.slice(prefix.length) : void 0;
|
|
149
89
|
}
|
|
150
90
|
/** The spellings a model-supplied container path may have degraded into. */
|
|
151
91
|
function containerCandidates(path) {
|
|
@@ -202,9 +142,10 @@ function joinMount(folder, relative) {
|
|
|
202
142
|
* @param path - a host path, a mixed-separator host path, an already-container
|
|
203
143
|
* path, or a path relative to the mount point.
|
|
204
144
|
* @param spec - the repository container specification.
|
|
145
|
+
* @param mounts - extra read-only mounts the runtime reported beside the workspace.
|
|
205
146
|
* @returns the POSIX container path; a path outside the repository comes back slash-normalized.
|
|
206
147
|
*/
|
|
207
|
-
function toContainerPath(path, spec) {
|
|
148
|
+
function toContainerPath(path, spec, mounts = []) {
|
|
208
149
|
const folder = spec.containerWorkspaceFolder;
|
|
209
150
|
if (path === "") return folder;
|
|
210
151
|
for (const candidate of containerCandidates(path)) {
|
|
@@ -217,24 +158,379 @@ function toContainerPath(path, spec) {
|
|
|
217
158
|
return normalized === "." ? folder : joinMount(folder, normalized);
|
|
218
159
|
}
|
|
219
160
|
const relative = relativeWithinHostRoot(path, spec.hostWorkspaceRoot);
|
|
220
|
-
if (relative
|
|
221
|
-
|
|
161
|
+
if (relative !== void 0) return relative === "" ? folder : joinMount(folder, relative);
|
|
162
|
+
for (const mount of mounts) {
|
|
163
|
+
const withinMount = relativeWithinHostRoot(path, mount.host);
|
|
164
|
+
if (withinMount === void 0) continue;
|
|
165
|
+
return withinMount === "" ? mount.sandbox : posix.join(mount.sandbox, withinMount);
|
|
166
|
+
}
|
|
167
|
+
return toPosixSlashes(path);
|
|
222
168
|
}
|
|
223
169
|
/**
|
|
224
170
|
* Translate one container path back into the host path of the bind mount.
|
|
225
171
|
* @param path - a container path, a drive-mangled container path, a host path, or a relative path.
|
|
226
172
|
* @param spec - the repository container specification.
|
|
173
|
+
* @param mounts - extra read-only mounts the runtime reported beside the workspace.
|
|
227
174
|
* @returns the native host path inside the repository, or `path` unchanged when it is not container-side.
|
|
228
175
|
*/
|
|
229
|
-
function toHostPath(path, spec) {
|
|
176
|
+
function toHostPath(path, spec, mounts = []) {
|
|
230
177
|
for (const candidate of containerCandidates(path)) {
|
|
231
178
|
const remainder = containerRemainder(candidate, spec.containerWorkspaceFolder);
|
|
232
179
|
if (remainder === void 0) continue;
|
|
233
180
|
return remainder === "" ? normalizeHostRoot(spec.hostWorkspaceRoot) : joinHostRoot(spec.hostWorkspaceRoot, remainder);
|
|
234
181
|
}
|
|
182
|
+
for (const candidate of containerCandidates(path)) for (const mount of mounts) {
|
|
183
|
+
const withinMount = containerRemainder(candidate, mount.sandbox, { fold: isWindowsPath(mount.host) });
|
|
184
|
+
if (withinMount === void 0) continue;
|
|
185
|
+
return withinMount === "" ? normalizeHostRoot(mount.host) : joinHostRoot(mount.host, withinMount);
|
|
186
|
+
}
|
|
235
187
|
return path;
|
|
236
188
|
}
|
|
237
189
|
//#endregion
|
|
190
|
+
//#region src/host-mounts.ts
|
|
191
|
+
/**
|
|
192
|
+
* The extra read-only host paths a Docker Sandbox mounts beside the workspace.
|
|
193
|
+
*
|
|
194
|
+
* A `(sbx)` session's filesystem fence ends at the workspace mount, so the host's
|
|
195
|
+
* global agent configuration — its `AGENTS.md` and its skill trees — is invisible
|
|
196
|
+
* from inside the sandbox. `sbx create` takes further host paths as positional
|
|
197
|
+
* arguments (`PATH[:TARGET][:ro]`), which is the one place they can be added: a
|
|
198
|
+
* single file must carry `:ro`, and a source that does not exist is a hard CLI
|
|
199
|
+
* failure, so this module decides what may be mounted before the argv is built.
|
|
200
|
+
* @module @banzhe/dsh-devcontainer/host-mounts
|
|
201
|
+
*/
|
|
202
|
+
/** What a row that configures nothing mounts: every default path that exists. */
|
|
203
|
+
const HOST_MOUNT_DEFAULTS = "auto";
|
|
204
|
+
/**
|
|
205
|
+
* Resolve the two user roots through DSH's own home rules, so an override the
|
|
206
|
+
* harness honours is the directory the sandbox mounts.
|
|
207
|
+
* @returns both roots, resolved and normalized.
|
|
208
|
+
*/
|
|
209
|
+
function hostMountHomes() {
|
|
210
|
+
return {
|
|
211
|
+
dshHome: normalizeHostRoot(resolveDshHome()),
|
|
212
|
+
agentsHome: normalizeHostRoot(resolveAgentsHome())
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
/** The optional mode token a mount expression ends with. */
|
|
216
|
+
const MODE_SUFFIX = /:(ro|rw)$/i;
|
|
217
|
+
/**
|
|
218
|
+
* Strip the mode token a mount expression or a listing entry ends with.
|
|
219
|
+
*
|
|
220
|
+
* `sbx` reports a read-only mount as `host:sandbox:ro`, so the token has to come
|
|
221
|
+
* off before the two paths are split — otherwise it stays on the sandbox side and
|
|
222
|
+
* names a path no sandbox has. One implementation serves the row's own entries and
|
|
223
|
+
* the listing, so the two cannot drift apart.
|
|
224
|
+
* @param entry - one mount expression, or one entry of a row's `mounts`/`workspaces` array.
|
|
225
|
+
* @returns the entry without its mode token, and whether it asked for read-only.
|
|
226
|
+
*/
|
|
227
|
+
function splitMountMode(entry) {
|
|
228
|
+
const match = MODE_SUFFIX.exec(entry);
|
|
229
|
+
if (match === null) return {
|
|
230
|
+
text: entry,
|
|
231
|
+
readOnly: false
|
|
232
|
+
};
|
|
233
|
+
return {
|
|
234
|
+
text: entry.slice(0, match.index),
|
|
235
|
+
readOnly: match[1]?.toLowerCase() === "ro"
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
/** A drive letter left dangling at the end of a path, as a split would leave it. */
|
|
239
|
+
const TRAILING_DRIVE = /:[A-Za-z]$/;
|
|
240
|
+
/**
|
|
241
|
+
* Split a `PATH[:/TARGET]` body into its host path and the sandbox path it asks for.
|
|
242
|
+
*
|
|
243
|
+
* The split point is the last `:/` whose left side is an absolute host path, so a
|
|
244
|
+
* drive colon stays part of the path however the drive is spelled: `D:\data\x`
|
|
245
|
+
* and `D:/data/x` both name no target, while `D:/data/x:/mnt/x` names `/mnt/x`.
|
|
246
|
+
* A body that splits nowhere names its tail as the target, which lets the reader
|
|
247
|
+
* reject the entry instead of mistaking a second path for part of the first.
|
|
248
|
+
* @param text - the expression with its mode token already removed.
|
|
249
|
+
* @returns the host path as written, and the target when the entry names one.
|
|
250
|
+
*/
|
|
251
|
+
function splitHostTarget(text) {
|
|
252
|
+
let separator = text.lastIndexOf(":/");
|
|
253
|
+
while (separator > 0) {
|
|
254
|
+
const candidate = text.slice(0, separator);
|
|
255
|
+
if ((isWindowsPath(candidate) || isPosixAbsolute(candidate)) && !TRAILING_DRIVE.test(candidate)) return {
|
|
256
|
+
host: candidate,
|
|
257
|
+
target: text.slice(separator + 1)
|
|
258
|
+
};
|
|
259
|
+
separator = text.lastIndexOf(":/", separator - 1);
|
|
260
|
+
}
|
|
261
|
+
const colon = text.indexOf(":", 2);
|
|
262
|
+
return colon === -1 ? { host: text } : {
|
|
263
|
+
host: text.slice(0, colon),
|
|
264
|
+
target: text.slice(colon + 1)
|
|
265
|
+
};
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* The sentence one entry with an unusable target is reported with.
|
|
269
|
+
* @param expression - the entry as the row configured it.
|
|
270
|
+
* @param target - the sandbox path it named.
|
|
271
|
+
* @returns the diagnostic, naming the entry and the rule it breaks.
|
|
272
|
+
*/
|
|
273
|
+
function targetRejection(expression, target) {
|
|
274
|
+
return "devcontainer: the host mount \"" + expression.trim() + "\" names the sandbox path \"" + target + "\", which is not an absolute path inside the sandbox; a target must start with \"/\" (for example \"/mnt/x.md\"), so this mount is skipped";
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* The sentence one entry whose target IS the sandbox root is reported with.
|
|
278
|
+
*
|
|
279
|
+
* Mounting a host directory at `/` would put it over everything the sandbox has,
|
|
280
|
+
* including the workspace, so the entry is refused rather than obeyed.
|
|
281
|
+
* @param expression - the entry as the row configured it.
|
|
282
|
+
* @param target - the sandbox path it named.
|
|
283
|
+
* @returns the diagnostic, naming the entry and the rule it breaks.
|
|
284
|
+
*/
|
|
285
|
+
function rootTargetRejection(expression, target) {
|
|
286
|
+
return "devcontainer: the host mount \"" + expression.trim() + "\" names the sandbox path \"" + target + "\", which is the sandbox root; a target must name a path inside the sandbox (for example \"/mnt/x.md\"), so this mount is skipped";
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* Read one entry of the row's list.
|
|
290
|
+
*
|
|
291
|
+
* The mode token goes first because only it is at the very end. A path in neither
|
|
292
|
+
* host style is kept as written: it cannot be mounted, and the diagnostic that
|
|
293
|
+
* names it should show what was typed. A target that is not POSIX-absolute — a
|
|
294
|
+
* second drive path, say — or that names the sandbox root makes the whole entry
|
|
295
|
+
* unusable: it is reported as such rather than re-read as part of the host path,
|
|
296
|
+
* which would turn a spelling mistake into a misleading "the source does not exist".
|
|
297
|
+
* @param expression - one entry of the row's `hostMounts` list.
|
|
298
|
+
* @returns the entry, or undefined for a blank one.
|
|
299
|
+
*/
|
|
300
|
+
function readEntry(expression) {
|
|
301
|
+
const text = expression.trim().replace(MODE_SUFFIX, "").trim();
|
|
302
|
+
if (text === "") return void 0;
|
|
303
|
+
const { host: spelled, target } = splitHostTarget(text);
|
|
304
|
+
const host = isWindowsPath(spelled) || isPosixAbsolute(spelled) ? normalizeHostRoot(spelled) : spelled;
|
|
305
|
+
if (target === void 0) return { mount: { host } };
|
|
306
|
+
if (!isPosixAbsolute(target)) return { rejection: targetRejection(expression, target) };
|
|
307
|
+
if (posix.normalize(toPosixSlashes(target)) === "/") return { rejection: rootTargetRejection(expression, target) };
|
|
308
|
+
return { mount: {
|
|
309
|
+
host,
|
|
310
|
+
target
|
|
311
|
+
} };
|
|
312
|
+
}
|
|
313
|
+
/**
|
|
314
|
+
* The configured entries that cannot be mounted as written.
|
|
315
|
+
* @param value - the row's `hostMounts` value.
|
|
316
|
+
* @returns one diagnostic per entry whose target is not a sandbox path.
|
|
317
|
+
*/
|
|
318
|
+
function hostMountRejections(value) {
|
|
319
|
+
const configured = value ?? "auto";
|
|
320
|
+
if (configured === "off" || configured === "auto") return [];
|
|
321
|
+
return configured.flatMap((expression) => {
|
|
322
|
+
const rejection = readEntry(expression)?.rejection;
|
|
323
|
+
return rejection === void 0 ? [] : [rejection];
|
|
324
|
+
});
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* Expand one configured value into the mounts a created sandbox asks for.
|
|
328
|
+
*
|
|
329
|
+
* `auto` is the host's shared agent configuration: the `AGENTS.md` each root may
|
|
330
|
+
* carry and the skill tree each may carry. `off` asks for nothing. A list is
|
|
331
|
+
* taken as written, in order, with the read-only token the CLI needs added by
|
|
332
|
+
* {@link hostMountArgument}. Nothing here looks at the host: whether a source
|
|
333
|
+
* exists is decided in {@link hostMountSourceExists}, at the moment a sandbox is
|
|
334
|
+
* created or started.
|
|
335
|
+
* @param value - the row's `hostMounts` value; omitted means {@link HOST_MOUNT_DEFAULTS}.
|
|
336
|
+
* @param homes - the two user roots, resolved by {@link hostMountHomes} by default.
|
|
337
|
+
* @returns the declared mounts, in the order the argv carries them.
|
|
338
|
+
*/
|
|
339
|
+
function hostMountPlan(value, homes = hostMountHomes()) {
|
|
340
|
+
const configured = value ?? "auto";
|
|
341
|
+
if (configured === "off") return [];
|
|
342
|
+
if (configured === "auto") return [
|
|
343
|
+
{ host: joinHostRoot(homes.dshHome, "AGENTS.md") },
|
|
344
|
+
{ host: joinHostRoot(homes.agentsHome, "AGENTS.md") },
|
|
345
|
+
{ host: joinHostRoot(homes.dshHome, "skills") },
|
|
346
|
+
{ host: joinHostRoot(homes.agentsHome, "skills") }
|
|
347
|
+
];
|
|
348
|
+
return configured.flatMap((expression) => {
|
|
349
|
+
const mount = readEntry(expression)?.mount;
|
|
350
|
+
return mount === void 0 ? [] : [mount];
|
|
351
|
+
});
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* The positional argument one mount becomes.
|
|
355
|
+
*
|
|
356
|
+
* Always read-only: the token is what lets `sbx` mount a single file at all, and
|
|
357
|
+
* a session that could write the host's skills or `AGENTS.md` would be editing
|
|
358
|
+
* configuration the container is not supposed to own.
|
|
359
|
+
* @param mount - the declared mount.
|
|
360
|
+
* @returns `host` or `host:target`, followed by `:ro`.
|
|
361
|
+
*/
|
|
362
|
+
function hostMountArgument(mount) {
|
|
363
|
+
const target = mount.target === void 0 ? "" : `:${mount.target}`;
|
|
364
|
+
return `${mount.host}${target}:ro`;
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* Whether the host path one mount names exists right now.
|
|
368
|
+
*
|
|
369
|
+
* `sbx` fails the whole `create` — or, once the sandbox exists, the automatic
|
|
370
|
+
* start behind `exec` — when a mount source is gone, and an interactive CLI may
|
|
371
|
+
* offer to create it. Neither is acceptable here: the source is the user's, so a
|
|
372
|
+
* missing one is reported and the mount is dropped instead.
|
|
373
|
+
* @param mount - the declared mount.
|
|
374
|
+
* @returns true when the host path is present.
|
|
375
|
+
*/
|
|
376
|
+
async function hostMountSourceExists(mount) {
|
|
377
|
+
try {
|
|
378
|
+
await access(mount.host);
|
|
379
|
+
return true;
|
|
380
|
+
} catch {
|
|
381
|
+
return false;
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Normalize a configured value a settings write or a Loader row may hand over.
|
|
386
|
+
*
|
|
387
|
+
* The field is volatile, so what a row holds is the live reference rather than the
|
|
388
|
+
* value inside it, and a write may land between two reads: it is unwrapped here,
|
|
389
|
+
* at the moment of use. A value the schema never validated — an absent row, a
|
|
390
|
+
* programmatic `apply` — reads as {@link HOST_MOUNT_DEFAULTS}, which is what the
|
|
391
|
+
* field defaults to.
|
|
392
|
+
* @param value - the configured value, in any state.
|
|
393
|
+
* @returns the value as {@link HostMountsConfig}.
|
|
394
|
+
*/
|
|
395
|
+
function hostMountsConfig(value) {
|
|
396
|
+
const held = typeof value?.get === "function" ? value.get() : value;
|
|
397
|
+
if (held === "auto" || held === "off") return held;
|
|
398
|
+
if (Array.isArray(held)) return held.filter((entry) => typeof entry === "string");
|
|
399
|
+
return HOST_MOUNT_DEFAULTS;
|
|
400
|
+
}
|
|
401
|
+
//#endregion
|
|
402
|
+
//#region src/sbx-template.ts
|
|
403
|
+
/**
|
|
404
|
+
* The image a Docker Sandbox is created with, as one argv token.
|
|
405
|
+
*
|
|
406
|
+
* The rule is shared by three callers that cannot reach each other's modules: the
|
|
407
|
+
* row schema that validates the setting, the settings page in the browser that
|
|
408
|
+
* writes it, and the argv builder that hands it to `sbx`. It therefore lives in a
|
|
409
|
+
* module of its own — no Node import — so all three read one definition instead of
|
|
410
|
+
* three copies.
|
|
411
|
+
* @module @banzhe/dsh-devcontainer/sbx-template
|
|
412
|
+
*/
|
|
413
|
+
/**
|
|
414
|
+
* What a configured image may look like: nothing at all, or one argv token with
|
|
415
|
+
* no whitespace of its own and no leading `-`.
|
|
416
|
+
*
|
|
417
|
+
* Surrounding whitespace is tolerated and trimmed, because the value is a person's
|
|
418
|
+
* typing and the token is what reaches the CLI. A leading `-` is not, because the
|
|
419
|
+
* CLI would read the value as another flag, and neither is an inner space, which
|
|
420
|
+
* `sbx` would split into two arguments.
|
|
421
|
+
*/
|
|
422
|
+
const SANDBOX_TEMPLATE_PATTERN = /^\s*(?:[^\s-]\S*)?\s*$/u;
|
|
423
|
+
/**
|
|
424
|
+
* The image one configured value names, trimmed, or undefined when it names none.
|
|
425
|
+
* @param value - the configured `sbxTemplate`.
|
|
426
|
+
* @returns the image to pass as `--template`, or undefined for the CLI's own template.
|
|
427
|
+
* @throws Error when the value cannot travel as one argv token.
|
|
428
|
+
*/
|
|
429
|
+
function sandboxTemplateOf(value) {
|
|
430
|
+
if (!SANDBOX_TEMPLATE_PATTERN.test(value)) throw new Error(`sbx: sbxTemplate ${JSON.stringify(value)} cannot be passed as one image name: it must contain no whitespace and must not start with "-"`);
|
|
431
|
+
const image = value.trim();
|
|
432
|
+
return image === "" ? void 0 : image;
|
|
433
|
+
}
|
|
434
|
+
//#endregion
|
|
435
|
+
//#region src/options.ts
|
|
436
|
+
/**
|
|
437
|
+
* The configuration fields every row of this Bundle shares. The three rows are
|
|
438
|
+
* separate Cordis plugins (one service each), and a repository's own file may
|
|
439
|
+
* override each of these per repository — the row's value is only the default
|
|
440
|
+
* discovery applies.
|
|
441
|
+
* @module @banzhe/dsh-devcontainer/options
|
|
442
|
+
*/
|
|
443
|
+
/** Defaults for {@link ContainerOptions}. */
|
|
444
|
+
const CONTAINER_OPTION_DEFAULTS = {
|
|
445
|
+
shell: "/bin/bash",
|
|
446
|
+
cli: "auto",
|
|
447
|
+
ensureUp: true,
|
|
448
|
+
containerTimeoutMs: 3e5,
|
|
449
|
+
requireContainer: false
|
|
450
|
+
};
|
|
451
|
+
/**
|
|
452
|
+
* Apply {@link CONTAINER_OPTION_DEFAULTS} to a possibly-partial configuration, so
|
|
453
|
+
* a programmatic `apply()` behaves like a Loader row whose schema already filled
|
|
454
|
+
* the defaults in.
|
|
455
|
+
* @param config - the row's configuration, or nothing.
|
|
456
|
+
* @returns the complete container options.
|
|
457
|
+
*/
|
|
458
|
+
function containerOptions(config = {}) {
|
|
459
|
+
return {
|
|
460
|
+
shell: config.shell ?? CONTAINER_OPTION_DEFAULTS.shell,
|
|
461
|
+
cli: config.cli ?? CONTAINER_OPTION_DEFAULTS.cli,
|
|
462
|
+
ensureUp: config.ensureUp ?? CONTAINER_OPTION_DEFAULTS.ensureUp,
|
|
463
|
+
containerTimeoutMs: config.containerTimeoutMs ?? CONTAINER_OPTION_DEFAULTS.containerTimeoutMs,
|
|
464
|
+
requireContainer: config.requireContainer ?? CONTAINER_OPTION_DEFAULTS.requireContainer
|
|
465
|
+
};
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* The shared Schemastery fields, spread into each row's `Config` so the three
|
|
469
|
+
* rows cannot drift apart. `cli` is `auto`: an explicit container wins, the
|
|
470
|
+
* running-container label lookup comes next, and the Dev Container CLI is the
|
|
471
|
+
* fallback that can start the container. `sbx` selects the Docker Sandbox
|
|
472
|
+
* driver, which mounts the host workspace instead of reading a declaration.
|
|
473
|
+
* @returns schemastery fields for {@link ContainerOptions}.
|
|
474
|
+
*/
|
|
475
|
+
function containerOptionFields() {
|
|
476
|
+
return {
|
|
477
|
+
shell: z.string().default(CONTAINER_OPTION_DEFAULTS.shell),
|
|
478
|
+
cli: z.union([
|
|
479
|
+
"auto",
|
|
480
|
+
"devcontainer",
|
|
481
|
+
"docker",
|
|
482
|
+
"sbx"
|
|
483
|
+
]).default(CONTAINER_OPTION_DEFAULTS.cli),
|
|
484
|
+
ensureUp: z.boolean().default(CONTAINER_OPTION_DEFAULTS.ensureUp),
|
|
485
|
+
containerTimeoutMs: z.number().default(CONTAINER_OPTION_DEFAULTS.containerTimeoutMs),
|
|
486
|
+
requireContainer: z.boolean().default(CONTAINER_OPTION_DEFAULTS.requireContainer)
|
|
487
|
+
};
|
|
488
|
+
}
|
|
489
|
+
/**
|
|
490
|
+
* The two preset-source fields as the Loader validates them.
|
|
491
|
+
*
|
|
492
|
+
* They are `volatile`, so a settings write lands in the live reference the Host
|
|
493
|
+
* row reads on its next sync instead of needing a reload, and they are defaults
|
|
494
|
+
* of the Host row only: the shell and filesystem rows have no preset set.
|
|
495
|
+
* @returns schemastery fields for {@link PresetSourceOptions}.
|
|
496
|
+
*/
|
|
497
|
+
function presetSourceFields() {
|
|
498
|
+
return {
|
|
499
|
+
sources: z.array(z.string()).default([]).volatile(),
|
|
500
|
+
sbxSources: z.array(z.string()).default([]).volatile()
|
|
501
|
+
};
|
|
502
|
+
}
|
|
503
|
+
/** Defaults for {@link SandboxTemplateOptions}: no image, so the CLI template stands. */
|
|
504
|
+
const SANDBOX_TEMPLATE_DEFAULTS = { sbxTemplate: "" };
|
|
505
|
+
/**
|
|
506
|
+
* The image field as the Loader validates it.
|
|
507
|
+
*
|
|
508
|
+
* It is `volatile`, so the settings page writes it into the live reference the
|
|
509
|
+
* rows read on their next command instead of needing a reload, and it is a default
|
|
510
|
+
* of the Host row only: the shell and filesystem rows have no settings page, and
|
|
511
|
+
* two more copies would be two more values to keep in step.
|
|
512
|
+
* @returns schemastery fields for {@link SandboxTemplateOptions}.
|
|
513
|
+
*/
|
|
514
|
+
function sandboxTemplateFields() {
|
|
515
|
+
return { sbxTemplate: z.string().default(SANDBOX_TEMPLATE_DEFAULTS.sbxTemplate).pattern(SANDBOX_TEMPLATE_PATTERN).volatile() };
|
|
516
|
+
}
|
|
517
|
+
/**
|
|
518
|
+
* The extra-mount field as the Loader validates it.
|
|
519
|
+
*
|
|
520
|
+
* A default of the Host row only, like the image: the rows that create a sandbox
|
|
521
|
+
* read it through the registry reader, so the value has one owner and one shape. It
|
|
522
|
+
* is `volatile` for the same reason the image is, so a settings write lands in the
|
|
523
|
+
* live reference the rows read on their next command.
|
|
524
|
+
* @returns schemastery fields for {@link HostMountOptions}.
|
|
525
|
+
*/
|
|
526
|
+
function hostMountFields() {
|
|
527
|
+
return { hostMounts: z.union([
|
|
528
|
+
z.const("auto"),
|
|
529
|
+
z.const("off"),
|
|
530
|
+
z.array(z.string())
|
|
531
|
+
]).default(HOST_MOUNT_DEFAULTS).volatile() };
|
|
532
|
+
}
|
|
533
|
+
//#endregion
|
|
238
534
|
//#region src/ids.ts
|
|
239
535
|
/**
|
|
240
536
|
* The suffixes and display labels that mark a derived preset, shared by both
|
|
@@ -444,6 +740,18 @@ function sbxRefusalText(workdir, preset) {
|
|
|
444
740
|
].join("\n");
|
|
445
741
|
}
|
|
446
742
|
/**
|
|
743
|
+
* The diagnostic a metadata probe outside every mount reports.
|
|
744
|
+
*
|
|
745
|
+
* A sandbox filesystem holds its workspace and the mounts its row declares; a probe
|
|
746
|
+
* of anything else is answered as the absence it is, in one line, without the escape
|
|
747
|
+
* wording a refused read or write gets.
|
|
748
|
+
* @param path - the path the probe named.
|
|
749
|
+
* @returns the diagnostic, ending without a newline so the seam reports it verbatim.
|
|
750
|
+
*/
|
|
751
|
+
function fsUnmountedText(path) {
|
|
752
|
+
return `devcontainer: "${path}" is not inside any mount of this session's container, so its filesystem has no such path`;
|
|
753
|
+
}
|
|
754
|
+
/**
|
|
447
755
|
* The diagnostic a refused filesystem call reports.
|
|
448
756
|
*
|
|
449
757
|
* It names the preset, the path, and every file discovery looked for, then the
|
|
@@ -951,6 +1259,116 @@ function repoRegistry(scope) {
|
|
|
951
1259
|
REGISTRIES.set(key, registry);
|
|
952
1260
|
return registry;
|
|
953
1261
|
}
|
|
1262
|
+
/** The live sandbox image one row publishes, per composition root. */
|
|
1263
|
+
const SANDBOX_TEMPLATES = /* @__PURE__ */ new WeakMap();
|
|
1264
|
+
/**
|
|
1265
|
+
* Publish the image the Host row configures right now to the composition's other
|
|
1266
|
+
* rows.
|
|
1267
|
+
*
|
|
1268
|
+
* `sbxTemplate` belongs to the Host row alone — the row the settings page writes,
|
|
1269
|
+
* because a page writes its own namespace — while the rows that run commands and
|
|
1270
|
+
* files are the ones that create a sandbox. The reader is registered once and
|
|
1271
|
+
* called at the moment a specification is built, so a settings write is answered
|
|
1272
|
+
* by the very next command instead of the next reload; nothing is copied at mount
|
|
1273
|
+
* time, when the profile patch may not have landed yet.
|
|
1274
|
+
* @param scope - the registering row's context.
|
|
1275
|
+
* @param read - the reader; returning undefined means "no image configured".
|
|
1276
|
+
* @returns the disposer that withdraws the reader.
|
|
1277
|
+
*/
|
|
1278
|
+
function registerSandboxTemplate(scope, read) {
|
|
1279
|
+
const key = rootOf(scope);
|
|
1280
|
+
SANDBOX_TEMPLATES.set(key, read);
|
|
1281
|
+
return () => {
|
|
1282
|
+
if (SANDBOX_TEMPLATES.get(key) === read) SANDBOX_TEMPLATES.delete(key);
|
|
1283
|
+
};
|
|
1284
|
+
}
|
|
1285
|
+
/**
|
|
1286
|
+
* The image this composition's Host row configures right now.
|
|
1287
|
+
* @param scope - the calling row's context.
|
|
1288
|
+
* @returns the image, or undefined when that row configured none or is not loaded.
|
|
1289
|
+
*/
|
|
1290
|
+
function liveSandboxTemplate(scope) {
|
|
1291
|
+
return scope === void 0 ? void 0 : SANDBOX_TEMPLATES.get(rootOf(scope))?.();
|
|
1292
|
+
}
|
|
1293
|
+
/** The live extra-host-mount configuration one row publishes, per composition root. */
|
|
1294
|
+
const HOST_MOUNTS = /* @__PURE__ */ new WeakMap();
|
|
1295
|
+
/**
|
|
1296
|
+
* Publish the extra host mounts the Host row configures right now.
|
|
1297
|
+
*
|
|
1298
|
+
* `hostMounts` belongs to the Host row alone, while the rows that create a sandbox
|
|
1299
|
+
* are the shell, filesystem, and subprocess ones — the same split `sbxTemplate`
|
|
1300
|
+
* has, and it is answered the same way: the reader is called when a specification
|
|
1301
|
+
* is built, never copied at mount time.
|
|
1302
|
+
* @param scope - the registering row's context.
|
|
1303
|
+
* @param read - the reader; it answers the value in force at this moment.
|
|
1304
|
+
* @returns the disposer that withdraws the reader.
|
|
1305
|
+
*/
|
|
1306
|
+
function registerHostMounts(scope, read) {
|
|
1307
|
+
const key = rootOf(scope);
|
|
1308
|
+
HOST_MOUNTS.set(key, read);
|
|
1309
|
+
return () => {
|
|
1310
|
+
if (HOST_MOUNTS.get(key) === read) HOST_MOUNTS.delete(key);
|
|
1311
|
+
};
|
|
1312
|
+
}
|
|
1313
|
+
/**
|
|
1314
|
+
* The extra host mounts this composition's Host row configures right now.
|
|
1315
|
+
* @param scope - the calling row's context.
|
|
1316
|
+
* @returns the configured value, or the schema default when no row published one.
|
|
1317
|
+
*/
|
|
1318
|
+
function liveHostMounts(scope) {
|
|
1319
|
+
return scope === void 0 ? HOST_MOUNT_DEFAULTS : HOST_MOUNTS.get(rootOf(scope))?.() ?? "auto";
|
|
1320
|
+
}
|
|
1321
|
+
/** The diagnostics one composition already reported, so a row cannot repeat another's. */
|
|
1322
|
+
const REPORTED = /* @__PURE__ */ new WeakMap();
|
|
1323
|
+
/**
|
|
1324
|
+
* Report one diagnostic once per composition.
|
|
1325
|
+
*
|
|
1326
|
+
* The shell, filesystem, and subprocess rows each resolve the same sandbox from
|
|
1327
|
+
* their own cache, so the same configuration mistake reaches several of them: a
|
|
1328
|
+
* person should read it once. The message carries the setting it is about, so a
|
|
1329
|
+
* changed setting is a new message and is reported again.
|
|
1330
|
+
* @param scope - the reporting row's context.
|
|
1331
|
+
* @param warn - where the message goes; nothing happens without one.
|
|
1332
|
+
* @param message - the diagnostic.
|
|
1333
|
+
*/
|
|
1334
|
+
function warnOnce(scope, warn, message) {
|
|
1335
|
+
if (warn === void 0) return;
|
|
1336
|
+
if (scope === void 0) {
|
|
1337
|
+
warn(message);
|
|
1338
|
+
return;
|
|
1339
|
+
}
|
|
1340
|
+
const key = rootOf(scope);
|
|
1341
|
+
let reported = REPORTED.get(key);
|
|
1342
|
+
if (reported === void 0) {
|
|
1343
|
+
reported = /* @__PURE__ */ new Set();
|
|
1344
|
+
REPORTED.set(key, reported);
|
|
1345
|
+
}
|
|
1346
|
+
if (reported.has(message)) return;
|
|
1347
|
+
reported.add(message);
|
|
1348
|
+
warn(message);
|
|
1349
|
+
}
|
|
1350
|
+
/**
|
|
1351
|
+
* The entries this composition's Host row configures that no argv can carry.
|
|
1352
|
+
* @param scope - the calling row's context.
|
|
1353
|
+
* @returns one diagnostic per unusable entry, empty when every entry is usable.
|
|
1354
|
+
*/
|
|
1355
|
+
function liveHostMountRejections(scope) {
|
|
1356
|
+
return hostMountRejections(liveHostMounts(scope));
|
|
1357
|
+
}
|
|
1358
|
+
/**
|
|
1359
|
+
* Read the live sandbox settings once, for one specification.
|
|
1360
|
+
* @param scope - the calling row's context.
|
|
1361
|
+
* @param options - the row's own container defaults.
|
|
1362
|
+
* @returns the builder options, carrying whatever the Host row configures right now.
|
|
1363
|
+
*/
|
|
1364
|
+
function liveSbxOptions(scope, options) {
|
|
1365
|
+
const template = liveSandboxTemplate(scope);
|
|
1366
|
+
return {
|
|
1367
|
+
...options,
|
|
1368
|
+
...template === void 0 ? {} : { sbxTemplate: template },
|
|
1369
|
+
hostMounts: liveHostMounts(scope)
|
|
1370
|
+
};
|
|
1371
|
+
}
|
|
954
1372
|
//#endregion
|
|
955
1373
|
//#region src/sbx.ts
|
|
956
1374
|
/**
|
|
@@ -969,16 +1387,60 @@ function repoRegistry(scope) {
|
|
|
969
1387
|
* nothing about the workspace keeps the host path as its fallback.
|
|
970
1388
|
*
|
|
971
1389
|
* The CLI surface used here is the documented one: `sbx ls --json` lists
|
|
972
|
-
* sandboxes, `sbx create --name <name> shell <path>` creates
|
|
973
|
-
* directory without attaching, and `sbx run -d --name <name>`
|
|
974
|
-
* sandbox detached. `sbx exec` reports a missing sandbox with
|
|
1390
|
+
* sandboxes, `sbx create --name <name> [--template <image>] shell <path>` creates
|
|
1391
|
+
* one around a host directory without attaching, and `sbx run -d --name <name>`
|
|
1392
|
+
* starts an existing sandbox detached. `sbx exec` reports a missing sandbox with
|
|
1393
|
+
* exit code 125.
|
|
975
1394
|
* @module @banzhe/dsh-devcontainer/sbx
|
|
976
1395
|
*/
|
|
977
1396
|
/** Prefix every sandbox this Bundle creates carries, so it is recognizable on a host. */
|
|
978
1397
|
const SANDBOX_NAME_PREFIX = "dsh-";
|
|
979
|
-
/** The
|
|
1398
|
+
/** The positional agent a created sandbox runs: Docker's agent-less shell agent. */
|
|
980
1399
|
const SANDBOX_TEMPLATE = "shell";
|
|
981
1400
|
/**
|
|
1401
|
+
* The flag that picks the IMAGE a created sandbox runs, as opposed to
|
|
1402
|
+
* {@link SANDBOX_TEMPLATE}, which is the agent it starts.
|
|
1403
|
+
*/
|
|
1404
|
+
const SANDBOX_TEMPLATE_FLAG = "--template";
|
|
1405
|
+
/**
|
|
1406
|
+
* The `--template` arguments one specification adds to `sbx create`.
|
|
1407
|
+
* @param spec - the sandbox specification.
|
|
1408
|
+
* @returns `['--template', image]`, or nothing when the row configured no image.
|
|
1409
|
+
* @throws Error when the configured value cannot travel as one argv token.
|
|
1410
|
+
*/
|
|
1411
|
+
function sandboxTemplateArgs(spec) {
|
|
1412
|
+
const image = spec.sbxTemplate === void 0 ? void 0 : sandboxTemplateOf(spec.sbxTemplate);
|
|
1413
|
+
return image === void 0 ? [] : [SANDBOX_TEMPLATE_FLAG, image];
|
|
1414
|
+
}
|
|
1415
|
+
/**
|
|
1416
|
+
* The extra read-only positionals one specification asks for, as declared.
|
|
1417
|
+
*
|
|
1418
|
+
* This is the argv shape without asking the host whether the sources exist, which
|
|
1419
|
+
* is what a diagnostic that names the command should show; `createSandbox`
|
|
1420
|
+
* filters it against the host before it runs.
|
|
1421
|
+
* @param spec - the sandbox specification.
|
|
1422
|
+
* @returns one `PATH[:TARGET]:ro` argument per declared mount, in declaration order.
|
|
1423
|
+
*/
|
|
1424
|
+
function hostMountArgsOf(spec) {
|
|
1425
|
+
return (spec.hostMounts ?? []).map(hostMountArgument);
|
|
1426
|
+
}
|
|
1427
|
+
/**
|
|
1428
|
+
* The tail of the `sbx create` argv one specification issues: the image flags,
|
|
1429
|
+
* the agent, the host directory to mount, and the extra read-only host paths.
|
|
1430
|
+
* @param spec - the sandbox specification.
|
|
1431
|
+
* @param extra - the extra mount arguments to append; the declared ones by default.
|
|
1432
|
+
* @returns the flags and positionals that follow `--name`.
|
|
1433
|
+
* @throws Error when the configured image cannot travel as one argv token.
|
|
1434
|
+
*/
|
|
1435
|
+
function createTailOf(spec, extra = hostMountArgsOf(spec)) {
|
|
1436
|
+
return [
|
|
1437
|
+
...sandboxTemplateArgs(spec),
|
|
1438
|
+
SANDBOX_TEMPLATE,
|
|
1439
|
+
spec.hostWorkspaceRoot,
|
|
1440
|
+
...extra
|
|
1441
|
+
];
|
|
1442
|
+
}
|
|
1443
|
+
/**
|
|
982
1444
|
* What a missing `sbx` CLI means for the person reading the diagnostic.
|
|
983
1445
|
*
|
|
984
1446
|
* The name is deliberately long-form: `command not found: sbx` says nothing
|
|
@@ -1014,28 +1476,77 @@ const RUNNING_STATES = /* @__PURE__ */ new Set([
|
|
|
1014
1476
|
"up",
|
|
1015
1477
|
"started"
|
|
1016
1478
|
]);
|
|
1479
|
+
/** The first string-valued field of a row, when it carries one. */
|
|
1480
|
+
function firstString(row, names) {
|
|
1481
|
+
for (const name of names) {
|
|
1482
|
+
const value = row[name];
|
|
1483
|
+
if (typeof value === "string" && value.trim() !== "") return value.trim();
|
|
1484
|
+
}
|
|
1485
|
+
}
|
|
1017
1486
|
/**
|
|
1018
1487
|
* Read one mount entry a listing reports.
|
|
1019
1488
|
*
|
|
1020
|
-
* The
|
|
1021
|
-
*
|
|
1022
|
-
*
|
|
1489
|
+
* The mode token and the two paths are read by the same splitter the row's own
|
|
1490
|
+
* `hostMounts` entries go through ({@link splitMountMode} and
|
|
1491
|
+
* {@link splitHostTarget}), so a listing and a configuration cannot disagree about
|
|
1492
|
+
* what one entry means. An entry that does not split into two absolute paths is
|
|
1023
1493
|
* dropped rather than guessed at, which leaves its sandbox on the host-path
|
|
1024
|
-
* fallback instead of a path that exists nowhere.
|
|
1494
|
+
* fallback instead of a path that exists nowhere. The object form is accepted
|
|
1495
|
+
* with the field names a later listing may use, so a release that switches from
|
|
1496
|
+
* the `host:sandbox` string to an object does not silently report no mounts.
|
|
1025
1497
|
* @param value - one entry of a row's `mounts` array.
|
|
1026
1498
|
* @returns the mount, or undefined when the entry names none.
|
|
1027
1499
|
*/
|
|
1028
1500
|
function sandboxMount(value) {
|
|
1029
|
-
if (typeof value
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1501
|
+
if (typeof value === "string") {
|
|
1502
|
+
const { text, readOnly } = splitMountMode(value.trim());
|
|
1503
|
+
const { host: spelled, target } = splitHostTarget(text);
|
|
1504
|
+
const host = spelled.trim();
|
|
1505
|
+
const sandbox = target?.trim();
|
|
1506
|
+
if (sandbox === void 0) return void 0;
|
|
1507
|
+
if (!isWindowsPath(host) && !isPosixAbsolute(host)) return void 0;
|
|
1508
|
+
if (!isPosixAbsolute(sandbox)) return void 0;
|
|
1509
|
+
return {
|
|
1510
|
+
host,
|
|
1511
|
+
sandbox,
|
|
1512
|
+
readOnly
|
|
1513
|
+
};
|
|
1514
|
+
}
|
|
1515
|
+
if (typeof value !== "object" || value === null) return void 0;
|
|
1516
|
+
const row = value;
|
|
1517
|
+
const host = firstString(row, [
|
|
1518
|
+
"host",
|
|
1519
|
+
"source",
|
|
1520
|
+
"src",
|
|
1521
|
+
"hostPath"
|
|
1522
|
+
]);
|
|
1523
|
+
const sandbox = firstString(row, [
|
|
1524
|
+
"sandbox",
|
|
1525
|
+
"destination",
|
|
1526
|
+
"dst",
|
|
1527
|
+
"target"
|
|
1528
|
+
]);
|
|
1529
|
+
if (host === void 0 || sandbox === void 0) return void 0;
|
|
1034
1530
|
if (!isWindowsPath(host) && !isPosixAbsolute(host)) return void 0;
|
|
1035
1531
|
if (!isPosixAbsolute(sandbox)) return void 0;
|
|
1036
1532
|
return {
|
|
1037
1533
|
host,
|
|
1038
|
-
sandbox
|
|
1534
|
+
sandbox,
|
|
1535
|
+
readOnly: row["readOnly"] === true || row["read_only"] === true
|
|
1536
|
+
};
|
|
1537
|
+
}
|
|
1538
|
+
/**
|
|
1539
|
+
* Read one `workspaces` entry, which is an absolute host path that may end in `:ro`.
|
|
1540
|
+
* @param value - one entry of a row's `workspaces` array.
|
|
1541
|
+
* @returns the workspace, or undefined when the entry names no absolute host path.
|
|
1542
|
+
*/
|
|
1543
|
+
function sandboxWorkspace(value) {
|
|
1544
|
+
if (typeof value !== "string") return void 0;
|
|
1545
|
+
const { text, readOnly } = splitMountMode(value.trim());
|
|
1546
|
+
if (!isWindowsPath(text) && !isPosixAbsolute(text)) return void 0;
|
|
1547
|
+
return {
|
|
1548
|
+
host: text,
|
|
1549
|
+
readOnly
|
|
1039
1550
|
};
|
|
1040
1551
|
}
|
|
1041
1552
|
/** The mounts one row reports, in the order it reports them. */
|
|
@@ -1044,6 +1555,12 @@ function mountsOf(row) {
|
|
|
1044
1555
|
if (!Array.isArray(listed)) return [];
|
|
1045
1556
|
return listed.map(sandboxMount).filter((mount) => mount !== void 0);
|
|
1046
1557
|
}
|
|
1558
|
+
/** The workspaces one row reports, in the order it reports them. */
|
|
1559
|
+
function workspacesOf(row) {
|
|
1560
|
+
const listed = row["workspaces"];
|
|
1561
|
+
if (!Array.isArray(listed)) return [];
|
|
1562
|
+
return listed.map(sandboxWorkspace).filter((workspace) => workspace !== void 0);
|
|
1563
|
+
}
|
|
1047
1564
|
/**
|
|
1048
1565
|
* Read one listed sandbox, tolerating the field names the CLI has used across
|
|
1049
1566
|
* releases (snake_case JSON, a `detached` flag, or a plain `running` boolean).
|
|
@@ -1060,23 +1577,27 @@ function listedSandbox(value) {
|
|
|
1060
1577
|
const name = row["name"];
|
|
1061
1578
|
if (typeof name !== "string" || name.trim() === "") return void 0;
|
|
1062
1579
|
const mounts = mountsOf(row);
|
|
1580
|
+
const workspaces = workspacesOf(row);
|
|
1063
1581
|
if (row["running"] === true || row["detached"] === true) return {
|
|
1064
1582
|
name: name.trim(),
|
|
1065
1583
|
running: true,
|
|
1066
|
-
mounts
|
|
1584
|
+
mounts,
|
|
1585
|
+
workspaces
|
|
1067
1586
|
};
|
|
1068
1587
|
for (const field of ["status", "state"]) {
|
|
1069
1588
|
const state = row[field];
|
|
1070
1589
|
if (typeof state === "string") return {
|
|
1071
1590
|
name: name.trim(),
|
|
1072
1591
|
running: RUNNING_STATES.has(state.trim().toLowerCase()),
|
|
1073
|
-
mounts
|
|
1592
|
+
mounts,
|
|
1593
|
+
workspaces
|
|
1074
1594
|
};
|
|
1075
1595
|
}
|
|
1076
1596
|
return {
|
|
1077
1597
|
name: name.trim(),
|
|
1078
1598
|
running: false,
|
|
1079
|
-
mounts
|
|
1599
|
+
mounts,
|
|
1600
|
+
workspaces
|
|
1080
1601
|
};
|
|
1081
1602
|
}
|
|
1082
1603
|
/**
|
|
@@ -1128,7 +1649,7 @@ async function listSandboxes(run, timeoutMs, signal) {
|
|
|
1128
1649
|
sandboxes: []
|
|
1129
1650
|
};
|
|
1130
1651
|
const sandboxes = parseSandboxList(result.stdout);
|
|
1131
|
-
|
|
1652
|
+
recordListing(sandboxes);
|
|
1132
1653
|
return {
|
|
1133
1654
|
available: true,
|
|
1134
1655
|
sandboxes
|
|
@@ -1203,21 +1724,135 @@ function sandboxMountFor(hostWorkspaceRoot, mounts) {
|
|
|
1203
1724
|
}
|
|
1204
1725
|
return found?.path;
|
|
1205
1726
|
}
|
|
1727
|
+
/** What is known about each sandbox, for the life of the process. */
|
|
1728
|
+
const sandboxRecords = /* @__PURE__ */ new Map();
|
|
1729
|
+
/** The record of one sandbox, created empty when nothing is known about it yet. */
|
|
1730
|
+
function recordOf(name) {
|
|
1731
|
+
const existing = sandboxRecords.get(name);
|
|
1732
|
+
if (existing !== void 0) return existing;
|
|
1733
|
+
const created = {
|
|
1734
|
+
mounts: [],
|
|
1735
|
+
workspaces: [],
|
|
1736
|
+
declared: []
|
|
1737
|
+
};
|
|
1738
|
+
sandboxRecords.set(name, created);
|
|
1739
|
+
return created;
|
|
1740
|
+
}
|
|
1741
|
+
/**
|
|
1742
|
+
* Remember one listing, so the synchronous builders below can read it.
|
|
1743
|
+
* @param sandboxes - the sandboxes the listing reported.
|
|
1744
|
+
*/
|
|
1745
|
+
function recordListing(sandboxes) {
|
|
1746
|
+
for (const sandbox of sandboxes) {
|
|
1747
|
+
const record = recordOf(sandbox.name);
|
|
1748
|
+
record.mounts = sandbox.mounts;
|
|
1749
|
+
record.workspaces = sandbox.workspaces;
|
|
1750
|
+
}
|
|
1751
|
+
}
|
|
1752
|
+
/**
|
|
1753
|
+
* Remember what one specification asks for, so a later attribution can name it.
|
|
1754
|
+
*
|
|
1755
|
+
* Only a specification a row BUILT carries a declared plan: one adopted from a
|
|
1756
|
+
* declaration has no say in what its host mounts, so it must not erase the plan
|
|
1757
|
+
* the row configured.
|
|
1758
|
+
* @param spec - the specification just built.
|
|
1759
|
+
*/
|
|
1760
|
+
function recordSpec(spec) {
|
|
1761
|
+
const record = recordOf(sandboxNameOf(spec));
|
|
1762
|
+
record.workspaceRoot = spec.hostWorkspaceRoot;
|
|
1763
|
+
if (spec.hostMounts !== void 0) record.declared = spec.hostMounts;
|
|
1764
|
+
}
|
|
1765
|
+
/** The host workspace of one sandbox, as its specification or its listing names it. */
|
|
1766
|
+
function workspaceRootOf(record) {
|
|
1767
|
+
return record.workspaceRoot ?? record.workspaces[0]?.host;
|
|
1768
|
+
}
|
|
1206
1769
|
/**
|
|
1207
|
-
* The
|
|
1770
|
+
* The host paths one sandbox accepts beside its workspace.
|
|
1771
|
+
*
|
|
1772
|
+
* Only the workspace and the mounts the row itself declares are here. The rest of
|
|
1773
|
+
* a listing — the agent skill store `sbx` injects, for one — belongs to the
|
|
1774
|
+
* sandbox's own machinery, and a session must not be able to name it, so nothing
|
|
1775
|
+
* is admitted merely because the listing reported it.
|
|
1208
1776
|
*
|
|
1209
|
-
*
|
|
1210
|
-
*
|
|
1211
|
-
*
|
|
1212
|
-
*
|
|
1777
|
+
* A listing without `workspaces` still names its workspace through the mount that
|
|
1778
|
+
* covers this specification's workspace root; that mount is the only one such a
|
|
1779
|
+
* row can be given outside the declared set.
|
|
1780
|
+
* @param record - what is known about the sandbox.
|
|
1781
|
+
* @returns the accepted mounts, the workspace first.
|
|
1213
1782
|
*/
|
|
1214
|
-
|
|
1783
|
+
function acceptedMounts(record) {
|
|
1784
|
+
const accepted = [];
|
|
1785
|
+
const reported = record.workspaces[0];
|
|
1786
|
+
const root = workspaceRootOf(record) ?? reported?.host;
|
|
1787
|
+
if (root !== void 0) {
|
|
1788
|
+
const sandbox = sandboxMountFor(root, record.mounts);
|
|
1789
|
+
if (sandbox !== void 0) accepted.push({
|
|
1790
|
+
host: normalizeHostRoot(root),
|
|
1791
|
+
sandbox,
|
|
1792
|
+
...reported?.readOnly === void 0 ? {} : { readOnly: reported.readOnly }
|
|
1793
|
+
});
|
|
1794
|
+
}
|
|
1795
|
+
for (const mount of declaredMounts(record.declared, record.mounts, record.mounts.length > 0)) {
|
|
1796
|
+
if (accepted.some((candidate) => sameHost(candidate.host, mount.host))) continue;
|
|
1797
|
+
accepted.push(mount);
|
|
1798
|
+
}
|
|
1799
|
+
return accepted;
|
|
1800
|
+
}
|
|
1215
1801
|
/**
|
|
1216
|
-
*
|
|
1217
|
-
*
|
|
1802
|
+
* Resolve declared host paths to the paths the sandbox really has for them.
|
|
1803
|
+
*
|
|
1804
|
+
* The listing is the authority: it reports where each host path was mounted, so a
|
|
1805
|
+
* declaration it does not mention was never mounted and is left out. A declaration
|
|
1806
|
+
* that names its own target needs no lookup, and the host convention answers only
|
|
1807
|
+
* before any listing has run — the same drive-letter rule a sandbox uses for its
|
|
1808
|
+
* workspace, and the only thing available at that point.
|
|
1809
|
+
*
|
|
1810
|
+
* That convention guess is a deliberate, accepted exception to "only what the
|
|
1811
|
+
* listing reported": the paths it admits are the row's own declarations, which are
|
|
1812
|
+
* exactly the ones just handed to `sbx create`, so it widens nothing a listing
|
|
1813
|
+
* would have named. If the sandbox mounted one of them elsewhere, a read there
|
|
1814
|
+
* fails with `FS_NOT_FOUND` — a missing file inside an accepted root, never a
|
|
1815
|
+
* fence that opens onto something else.
|
|
1816
|
+
* @param declared - the host paths a row asked to mount.
|
|
1817
|
+
* @param mounts - the mounts a listing reported.
|
|
1818
|
+
* @param listed - whether a listing has reported this sandbox at all.
|
|
1819
|
+
* @returns one read-only mount per declaration the sandbox carries.
|
|
1218
1820
|
*/
|
|
1219
|
-
function
|
|
1220
|
-
|
|
1821
|
+
function declaredMounts(declared, mounts, listed) {
|
|
1822
|
+
const resolved = [];
|
|
1823
|
+
for (const mount of declared) {
|
|
1824
|
+
const host = normalizeHostRoot(mount.host);
|
|
1825
|
+
const reported = sandboxMountFor(host, mounts);
|
|
1826
|
+
const sandbox = mount.target ?? reported ?? (listed ? void 0 : sandboxWorkspacePath(host));
|
|
1827
|
+
if (sandbox === void 0) continue;
|
|
1828
|
+
resolved.push({
|
|
1829
|
+
host,
|
|
1830
|
+
sandbox,
|
|
1831
|
+
readOnly: true
|
|
1832
|
+
});
|
|
1833
|
+
}
|
|
1834
|
+
return resolved;
|
|
1835
|
+
}
|
|
1836
|
+
/** Whether two host paths name the same file or directory, folding win32 case. */
|
|
1837
|
+
function sameHost(left, right) {
|
|
1838
|
+
return relativeWithinHostRoot(left, right) === "" || relativeWithinHostRoot(right, left) === "";
|
|
1839
|
+
}
|
|
1840
|
+
/**
|
|
1841
|
+
* The extra read-only mounts one specification's sandbox carries.
|
|
1842
|
+
*
|
|
1843
|
+
* These are the paths a session may name beside its workspace, and nothing else a
|
|
1844
|
+
* listing reports: the fence, the path translation, and the helper's own guard are
|
|
1845
|
+
* all built from this list.
|
|
1846
|
+
* @param spec - the repository container specification.
|
|
1847
|
+
* @returns the declared mounts with their sandbox spellings; empty when none resolves.
|
|
1848
|
+
*/
|
|
1849
|
+
function sbxExtraMountsOf(spec) {
|
|
1850
|
+
if (spec.cli !== "sbx") return [];
|
|
1851
|
+
const record = sandboxRecords.get(sandboxNameOf(spec));
|
|
1852
|
+
const declared = spec.hostMounts ?? record?.declared ?? [];
|
|
1853
|
+
if (declared.length === 0) return [];
|
|
1854
|
+
const mounts = record?.mounts ?? [];
|
|
1855
|
+
return declaredMounts(declared, mounts, mounts.length > 0);
|
|
1221
1856
|
}
|
|
1222
1857
|
/**
|
|
1223
1858
|
* The host directory a path inside a sandbox names.
|
|
@@ -1243,31 +1878,59 @@ function sandboxHostPathFor(sandboxPath) {
|
|
|
1243
1878
|
const normalized = posix.normalize(toPosixSlashes(sandboxPath));
|
|
1244
1879
|
if (!isPosixAbsolute(normalized)) return void 0;
|
|
1245
1880
|
const mounted = mountedHostFor(normalized);
|
|
1246
|
-
if (mounted !== void 0) return
|
|
1247
|
-
host: mounted.host,
|
|
1248
|
-
workspaceRoot: normalizeHostRoot(mounted.root)
|
|
1249
|
-
};
|
|
1881
|
+
if (mounted !== void 0) return mounted;
|
|
1250
1882
|
const drive = driveHostFor(normalized);
|
|
1251
1883
|
return drive === void 0 ? void 0 : { host: drive };
|
|
1252
1884
|
}
|
|
1253
|
-
/**
|
|
1254
|
-
|
|
1885
|
+
/**
|
|
1886
|
+
* The sandbox whose workspace or declared extra mount covers one HOST path.
|
|
1887
|
+
*
|
|
1888
|
+
* A session names `C:\Users\me\.dsh\AGENTS.md` the way the host spells it, while
|
|
1889
|
+
* the sandbox that mounted it is the one whose workspace the session runs in — not
|
|
1890
|
+
* a sandbox invented around that file. This answers which one it is.
|
|
1891
|
+
* @param hostPath - an absolute host path.
|
|
1892
|
+
* @returns the host path and its sandbox, or undefined when no sandbox mounts it.
|
|
1893
|
+
*/
|
|
1894
|
+
function sbxMountAttribution(hostPath) {
|
|
1895
|
+
const normalized = normalizeHostRoot(hostPath);
|
|
1255
1896
|
let found;
|
|
1256
|
-
for (const
|
|
1257
|
-
const relative =
|
|
1897
|
+
for (const [name, record] of sandboxRecords) for (const mount of acceptedMounts(record)) {
|
|
1898
|
+
const relative = relativeWithinHostRoot(normalized, mount.host);
|
|
1258
1899
|
if (relative === void 0) continue;
|
|
1259
|
-
|
|
1260
|
-
|
|
1900
|
+
if (found !== void 0 && found.length >= mount.host.length) continue;
|
|
1901
|
+
const workspaceRoot = workspaceRootOf(record);
|
|
1261
1902
|
found = {
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1903
|
+
length: mount.host.length,
|
|
1904
|
+
attribution: {
|
|
1905
|
+
host: relative === "" ? normalizeHostRoot(mount.host) : joinHostRoot(mount.host, relative),
|
|
1906
|
+
...workspaceRoot === void 0 ? {} : { workspaceRoot: normalizeHostRoot(workspaceRoot) },
|
|
1907
|
+
sandbox: name
|
|
1908
|
+
}
|
|
1265
1909
|
};
|
|
1266
1910
|
}
|
|
1267
|
-
return found
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1911
|
+
return found?.attribution;
|
|
1912
|
+
}
|
|
1913
|
+
/** The host directory and workspace a reported mount covers, the deepest mount winning. */
|
|
1914
|
+
function mountedHostFor(sandboxPath) {
|
|
1915
|
+
let found;
|
|
1916
|
+
for (const [name, record] of sandboxRecords) {
|
|
1917
|
+
const workspaceRoot = workspaceRootOf(record);
|
|
1918
|
+
for (const mount of acceptedMounts(record)) {
|
|
1919
|
+
const relative = containerRemainder(sandboxPath, mount.sandbox);
|
|
1920
|
+
if (relative === void 0) continue;
|
|
1921
|
+
const depth = posix.normalize(mount.sandbox).length;
|
|
1922
|
+
if (found !== void 0 && found.depth >= depth) continue;
|
|
1923
|
+
found = {
|
|
1924
|
+
depth,
|
|
1925
|
+
attribution: {
|
|
1926
|
+
host: relative === "" ? normalizeHostRoot(mount.host) : joinHostRoot(mount.host, relative),
|
|
1927
|
+
workspaceRoot: normalizeHostRoot(workspaceRoot ?? mount.host),
|
|
1928
|
+
sandbox: name
|
|
1929
|
+
}
|
|
1930
|
+
};
|
|
1931
|
+
}
|
|
1932
|
+
}
|
|
1933
|
+
return found?.attribution;
|
|
1271
1934
|
}
|
|
1272
1935
|
/** The drive-letter directory a sandbox path spells on a Windows host, when its first segment is a letter. */
|
|
1273
1936
|
function driveHostFor(sandboxPath) {
|
|
@@ -1291,7 +1954,7 @@ function sandboxNameOf(spec) {
|
|
|
1291
1954
|
* @returns the absolute sandbox path, or undefined when no listing covered the workspace.
|
|
1292
1955
|
*/
|
|
1293
1956
|
function sbxMountOf(spec) {
|
|
1294
|
-
const mounts =
|
|
1957
|
+
const mounts = sandboxRecords.get(sandboxNameOf(spec))?.mounts;
|
|
1295
1958
|
return mounts === void 0 ? void 0 : sandboxMountFor(spec.hostWorkspaceRoot, mounts);
|
|
1296
1959
|
}
|
|
1297
1960
|
/**
|
|
@@ -1335,16 +1998,27 @@ function asSbxSpec(spec, mounts) {
|
|
|
1335
1998
|
}
|
|
1336
1999
|
/**
|
|
1337
2000
|
* The sandbox specification of one host directory, declared or not.
|
|
2001
|
+
*
|
|
2002
|
+
* The image a created sandbox runs is the Host row's `sbxTemplate` and nothing
|
|
2003
|
+
* else's: a declaration cannot choose the image of the host that mounts it. The
|
|
2004
|
+
* caller passes the value the Host row configures at this moment
|
|
2005
|
+
* (`liveSandboxTemplate`) on `options.sbxTemplate`, so a settings write is
|
|
2006
|
+
* answered by the next command, and it is carried on the specification so
|
|
2007
|
+
* `createSandbox` and the diagnostic that names the command both read the same one.
|
|
2008
|
+
*
|
|
2009
|
+
* The extra host mounts are the Host row's too, for the same reason: they are the
|
|
2010
|
+
* paths a sandbox mounts beside this workspace, and a declaration has no say in
|
|
2011
|
+
* them. The plan is carried on the specification, where the fence, the path
|
|
2012
|
+
* translation, and the helper's guard read it.
|
|
1338
2013
|
* @param hostWorkspaceRoot - absolute host path of the workspace.
|
|
1339
|
-
* @param options - the row's container defaults.
|
|
2014
|
+
* @param options - the row's container defaults, plus the image and mounts configured right now.
|
|
1340
2015
|
* @param declared - the specification a declaration produced, when one exists.
|
|
1341
2016
|
* @param mounts - the mounts of a fresh listing; when absent, the mounts the last one reported are used.
|
|
1342
2017
|
* @returns the specification a `(sbx)` session runs under.
|
|
1343
2018
|
*/
|
|
1344
2019
|
function sbxSpecFor(hostWorkspaceRoot, options, declared, mounts) {
|
|
1345
2020
|
const root = normalizeHostRoot(hostWorkspaceRoot);
|
|
1346
|
-
|
|
1347
|
-
return asSbxSpec({
|
|
2021
|
+
const spec = declared !== void 0 && normalizeHostRoot(declared.hostWorkspaceRoot) === root ? asSbxSpec(declared, mounts) : asSbxSpec({
|
|
1348
2022
|
hostWorkspaceRoot: root,
|
|
1349
2023
|
containerWorkspaceFolder: sandboxWorkspacePath(root) ?? root,
|
|
1350
2024
|
configPath: "",
|
|
@@ -1353,6 +2027,13 @@ function sbxSpecFor(hostWorkspaceRoot, options, declared, mounts) {
|
|
|
1353
2027
|
ensureUp: options.ensureUp,
|
|
1354
2028
|
containerTimeoutMs: options.containerTimeoutMs
|
|
1355
2029
|
}, mounts);
|
|
2030
|
+
const image = options.sbxTemplate?.trim() ?? "";
|
|
2031
|
+
const { sbxTemplate: _declared, hostMounts: _declaredMounts, ...rest } = spec;
|
|
2032
|
+
return {
|
|
2033
|
+
...rest,
|
|
2034
|
+
hostMounts: hostMountPlan(options.hostMounts),
|
|
2035
|
+
...image === "" ? {} : { sbxTemplate: image }
|
|
2036
|
+
};
|
|
1356
2037
|
}
|
|
1357
2038
|
/**
|
|
1358
2039
|
* Align a specification with the mount its resolved target reports.
|
|
@@ -1375,21 +2056,106 @@ function failureDetail(result) {
|
|
|
1375
2056
|
return (result.stderr.trim() || result.stdout.trim() || "no output").split("\n").slice(-3).join(" ");
|
|
1376
2057
|
}
|
|
1377
2058
|
/**
|
|
2059
|
+
* The declared mounts whose host source is gone.
|
|
2060
|
+
* @param spec - the sandbox specification.
|
|
2061
|
+
* @returns the declarations whose path does not exist right now.
|
|
2062
|
+
*/
|
|
2063
|
+
async function missingHostMounts(spec) {
|
|
2064
|
+
const missing = [];
|
|
2065
|
+
for (const mount of spec.hostMounts ?? []) if (!await hostMountSourceExists(mount)) missing.push(mount);
|
|
2066
|
+
return missing;
|
|
2067
|
+
}
|
|
2068
|
+
/**
|
|
2069
|
+
* The declared mounts one existing sandbox did not take.
|
|
2070
|
+
*
|
|
2071
|
+
* The listing's `workspaces` is what answers, in order: the first entry is the
|
|
2072
|
+
* workspace, so a declaration missing from the rest was never mounted — it did not
|
|
2073
|
+
* exist when the sandbox was created. A listing that reports no `workspaces` is
|
|
2074
|
+
* read through its mounts, which is all an older CLI offers.
|
|
2075
|
+
* @param spec - the sandbox specification.
|
|
2076
|
+
* @param listed - the sandbox as the listing reports it.
|
|
2077
|
+
* @returns the declarations that sandbox does not mount.
|
|
2078
|
+
*/
|
|
2079
|
+
function unmountedHostMounts(spec, listed) {
|
|
2080
|
+
const declared = spec.hostMounts ?? [];
|
|
2081
|
+
if (declared.length === 0) return [];
|
|
2082
|
+
const mounted = listed.workspaces.length === 0 ? listed.mounts.map((mount) => mount.host) : listed.workspaces.map((workspace) => workspace.host);
|
|
2083
|
+
return declared.filter((mount) => !mounted.some((host) => sameHost(host, mount.host)));
|
|
2084
|
+
}
|
|
2085
|
+
/** The one sentence a mount whose source is gone is reported with. */
|
|
2086
|
+
function missingHostMountText(mount, sandboxName) {
|
|
2087
|
+
return "devcontainer: the host mount source \"" + mount.host + "\" does not exist, so it is not mounted in sandbox \"" + sandboxName + "\"; create it, then remove the sandbox (\"sbx rm " + sandboxName + "\") so it is created with that mount";
|
|
2088
|
+
}
|
|
2089
|
+
/** The one sentence a mount the sandbox carries whose host source vanished is reported with. */
|
|
2090
|
+
function brokenHostMountText(mount, sandboxName) {
|
|
2091
|
+
return "devcontainer: sandbox \"" + sandboxName + "\" mounts \"" + mount.host + "\", whose source no longer exists on the host; restore it, or remove the sandbox (\"sbx rm " + sandboxName + "\") so it is created without that mount";
|
|
2092
|
+
}
|
|
2093
|
+
/** The one sentence a declaration an existing sandbox never took is reported with. */
|
|
2094
|
+
function unmountedHostMountText(mount, sandboxName) {
|
|
2095
|
+
return "devcontainer: sandbox \"" + sandboxName + "\" does not mount \"" + mount.host + "\", which this row declares; remove the sandbox (\"sbx rm " + sandboxName + "\") so it is created with that mount";
|
|
2096
|
+
}
|
|
2097
|
+
/** The failure of a start that cannot succeed, worded as what to do about it. */
|
|
2098
|
+
function missingMountStartText(sandboxName, mounts) {
|
|
2099
|
+
const paths = mounts.map((mount) => "\"" + mount.host + "\"").join(", ");
|
|
2100
|
+
return "sbx: Docker Sandbox \"" + sandboxName + "\" cannot start: the host mount source " + paths + " no longer exists. Restore it, or remove the sandbox (\"sbx rm " + sandboxName + "\") so it is created without that mount.";
|
|
2101
|
+
}
|
|
2102
|
+
/**
|
|
2103
|
+
* Report every declared mount the host or the sandbox does not carry.
|
|
2104
|
+
*
|
|
2105
|
+
* Only a mount the sandbox actually carries can make a start fail, so that is the
|
|
2106
|
+
* one case reported as a state a start cannot survive. A declaration whose source
|
|
2107
|
+
* is gone and that the sandbox never took is the ordinary `auto` situation — the
|
|
2108
|
+
* host has no `~/.agents/AGENTS.md`, say — and a sandbox without that mount starts
|
|
2109
|
+
* exactly as it always did; it is reported, never refused.
|
|
2110
|
+
* @param spec - the sandbox specification.
|
|
2111
|
+
* @param listed - the sandbox as the listing reports it.
|
|
2112
|
+
* @param warn - where the reports go; nothing is reported without one.
|
|
2113
|
+
* @returns the declarations the sandbox mounts whose host source is gone.
|
|
2114
|
+
*/
|
|
2115
|
+
async function reportMountState(spec, listed, warn) {
|
|
2116
|
+
const name = sandboxNameOf(spec);
|
|
2117
|
+
const missing = await missingHostMounts(spec);
|
|
2118
|
+
const unmounted = unmountedHostMounts(spec, listed);
|
|
2119
|
+
const broken = [];
|
|
2120
|
+
for (const mount of missing) {
|
|
2121
|
+
if (unmounted.some((candidate) => sameHost(candidate.host, mount.host))) {
|
|
2122
|
+
warn?.(missingHostMountText(mount, name));
|
|
2123
|
+
continue;
|
|
2124
|
+
}
|
|
2125
|
+
warn?.(brokenHostMountText(mount, name));
|
|
2126
|
+
broken.push(mount);
|
|
2127
|
+
}
|
|
2128
|
+
for (const mount of unmounted) {
|
|
2129
|
+
if (missing.some((candidate) => sameHost(candidate.host, mount.host))) continue;
|
|
2130
|
+
warn?.(unmountedHostMountText(mount, name));
|
|
2131
|
+
}
|
|
2132
|
+
return broken;
|
|
2133
|
+
}
|
|
2134
|
+
/**
|
|
1378
2135
|
* Create one sandbox around a host workspace, without attaching to it.
|
|
2136
|
+
*
|
|
2137
|
+
* The extra host mounts are appended as positional arguments, and only the ones
|
|
2138
|
+
* whose source exists right now: `sbx` fails the whole creation for a missing
|
|
2139
|
+
* source, and an interactive CLI offers to create one, which a session must never
|
|
2140
|
+
* do to a host path it was only given to read.
|
|
1379
2141
|
* @param spec - the sandbox specification.
|
|
1380
2142
|
* @param sandboxName - the name to create.
|
|
1381
2143
|
* @param run - the CLI runner.
|
|
1382
2144
|
* @param signal - cancellation.
|
|
2145
|
+
* @param warn - reports each declared mount whose source is gone.
|
|
1383
2146
|
* @throws Error when `sbx` is missing or the creation failed.
|
|
1384
2147
|
*/
|
|
1385
|
-
async function createSandbox(spec, sandboxName, run, signal) {
|
|
2148
|
+
async function createSandbox(spec, sandboxName, run, signal, warn) {
|
|
2149
|
+
recordSpec(spec);
|
|
2150
|
+
const extra = [];
|
|
2151
|
+
for (const mount of spec.hostMounts ?? []) if (await hostMountSourceExists(mount)) extra.push(hostMountArgument(mount));
|
|
2152
|
+
else warn?.(missingHostMountText(mount, sandboxName));
|
|
1386
2153
|
const result = await run([
|
|
1387
2154
|
"sbx",
|
|
1388
2155
|
"create",
|
|
1389
2156
|
"--name",
|
|
1390
2157
|
sandboxName,
|
|
1391
|
-
|
|
1392
|
-
spec.hostWorkspaceRoot
|
|
2158
|
+
...createTailOf(spec, extra)
|
|
1393
2159
|
], {
|
|
1394
2160
|
...signal === void 0 ? {} : { signal },
|
|
1395
2161
|
timeoutMs: spec.containerTimeoutMs
|
|
@@ -1461,29 +2227,46 @@ async function assertSandboxNode(spec, sandboxName, run, signal) {
|
|
|
1461
2227
|
*
|
|
1462
2228
|
* The listing also names the mounts, so the returned target carries the folder
|
|
1463
2229
|
* the sandbox really has for this workspace instead of the host spelling.
|
|
2230
|
+
*
|
|
2231
|
+
* The extra host mounts are the one thing a sandbox cannot gain after it exists,
|
|
2232
|
+
* so this is also where their state is reported: a missing source is a diagnostic
|
|
2233
|
+
* (and, for a sandbox that has to start, a refusal worded as what to do), and a
|
|
2234
|
+
* declaration the sandbox never took is the same `sbx rm` advice. Nothing here
|
|
2235
|
+
* removes or recreates a sandbox — that is the user's call.
|
|
1464
2236
|
* @param spec - the sandbox specification.
|
|
1465
2237
|
* @param run - the CLI runner.
|
|
1466
2238
|
* @param signal - cancellation of the probe / start sequence.
|
|
2239
|
+
* @param warn - reports a mount the sandbox does not carry, and a source that is gone.
|
|
1467
2240
|
* @returns the sandbox target.
|
|
1468
|
-
* @throws Error when `sbx` is missing, the sandbox cannot be prepared, one is required and absent,
|
|
2241
|
+
* @throws Error when `sbx` is missing, the sandbox cannot be prepared, one is required and absent, it has no Node.js, or a start would fail on a mount the sandbox carries whose source is gone.
|
|
1469
2242
|
*/
|
|
1470
|
-
async function resolveSbxTarget(spec, run, signal) {
|
|
2243
|
+
async function resolveSbxTarget(spec, run, signal, warn) {
|
|
1471
2244
|
const name = sandboxNameOf(spec);
|
|
2245
|
+
recordSpec(spec);
|
|
1472
2246
|
const listing = await listSandboxes(run, spec.containerTimeoutMs, signal);
|
|
1473
2247
|
if (!listing.available) throw new Error(`sbx: ${SBX_INSTALL_HINT}`);
|
|
1474
2248
|
const listed = listing.sandboxes.find((sandbox) => sandbox.name === name);
|
|
1475
2249
|
const target = sbxTargetOf(spec, listed?.mounts ?? []);
|
|
1476
2250
|
if (listed?.running === true) {
|
|
2251
|
+
await reportMountState(spec, listed, warn);
|
|
1477
2252
|
await assertSandboxNode(spec, name, run, signal);
|
|
1478
2253
|
return target;
|
|
1479
2254
|
}
|
|
1480
|
-
if (!spec.ensureUp) throw new Error(listed === void 0 ? `sbx: no Docker Sandbox named "${name}" exists for "${spec.hostWorkspaceRoot}"; create it with "sbx create --name ${name} ${
|
|
1481
|
-
if (listed === void 0)
|
|
2255
|
+
if (!spec.ensureUp) throw new Error(listed === void 0 ? `sbx: no Docker Sandbox named "${name}" exists for "${spec.hostWorkspaceRoot}"; create it with "sbx create --name ${name} ${createTailOf(spec).join(" ")}", or set ensureUp: true` : `sbx: Docker Sandbox "${name}" for "${spec.hostWorkspaceRoot}" is not running; start it with "sbx run --detach --name ${name}", or set ensureUp: true`);
|
|
2256
|
+
if (listed === void 0) {
|
|
2257
|
+
await createSandbox(spec, name, run, signal, warn);
|
|
2258
|
+
await startSandbox(spec, name, run, signal);
|
|
2259
|
+
await assertSandboxNode(spec, name, run, signal);
|
|
2260
|
+
if ((spec.hostMounts ?? []).length === 0) return target;
|
|
2261
|
+
return sbxTargetOf(spec, (await listSandboxes(run, spec.containerTimeoutMs, signal)).sandboxes.find((sandbox) => sandbox.name === name)?.mounts ?? []);
|
|
2262
|
+
}
|
|
2263
|
+
const missing = await reportMountState(spec, listed, warn);
|
|
2264
|
+
if (missing.length > 0) throw new Error(missingMountStartText(name, missing));
|
|
1482
2265
|
await startSandbox(spec, name, run, signal);
|
|
1483
2266
|
await assertSandboxNode(spec, name, run, signal);
|
|
1484
2267
|
return target;
|
|
1485
2268
|
}
|
|
1486
2269
|
//#endregion
|
|
1487
|
-
export {
|
|
2270
|
+
export { toHostPath as $, markedVariantKind as A, containerOptions as B, callingVariantKind as C, fsUnmountedText as D, fsRefusalText as E, VARIANT_KINDS as F, containerRemainder as G, presetSourceFields as H, variantIdOf as I, isPosixAbsolute as J, hostPathStyle as K, variantKindOf as L, refusalText as M, refusedExecution as N, markedContainerOnly as O, sbxRefusalText as P, toContainerPath as Q, variantNameSuffixOf as R, callingContainerPreset as S, fsEscapeRefusalText as T, sandboxTemplateFields as U, hostMountFields as V, hostMountsConfig as W, joinHostRoot as X, isWindowsPath as Y, relativeWithinHostRoot as Z, CONTAINER_MARKER_KEYS as _, sandboxNameFor as a, SBX_ENV_KEY as b, sbxMountAttribution as c, liveHostMountRejections as d, toPosixSlashes as et, liveSbxOptions as f, warnOnce as g, repoRegistry as h, sandboxHostPathFor as i, presetKindOf as j, markedPreset as k, sbxSpecFor as l, registerSandboxTemplate as m, bindSbxMount as n, sandboxWorkspacePath as o, registerHostMounts as p, isPathInsideContainer as q, resolveSbxTarget as r, sbxExtraMountsOf as s, asSbxSpec as t, sbxWorkspaceRootFor as u, DEVCONTAINER_ENV_KEY as v, containerPresetOf as w, SBX_PRESET_ENV_KEY as x, DEVCONTAINER_PRESET_ENV_KEY as y, containerOptionFields as z };
|
|
1488
2271
|
|
|
1489
|
-
//# sourceMappingURL=sbx-
|
|
2272
|
+
//# sourceMappingURL=sbx-Blgjzzoe.js.map
|