@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.
@@ -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
- if (normalized === root) return "";
147
- const prefix = root.endsWith("/") ? root : `${root}/`;
148
- return normalized.startsWith(prefix) ? normalized.slice(prefix.length) : void 0;
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 === void 0) return toPosixSlashes(path);
221
- return relative === "" ? folder : joinMount(folder, relative);
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 one around a host
973
- * directory without attaching, and `sbx run -d --name <name>` starts an existing
974
- * sandbox detached. `sbx exec` reports a missing sandbox with exit code 125.
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 template a created sandbox runs: Docker's agent-less shell template. */
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 separator is the LAST `:/` of the entry: a Windows host directory carries a
1021
- * drive colon of its own, while the sandbox side of a mount is always
1022
- * POSIX-absolute. An entry that does not split into two absolute paths is
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 !== "string") return void 0;
1030
- const separator = value.lastIndexOf(":/");
1031
- if (separator <= 0) return void 0;
1032
- const host = value.slice(0, separator).trim();
1033
- const sandbox = value.slice(separator + 1).trim();
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
- recordMounts(sandboxes);
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 mounts the last listing reported, per sandbox name.
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
- * {@link sbxSpecFor} and {@link asSbxSpec} are synchronous — the preset builder,
1210
- * the filesystem route, and the spawn-cwd mapping all build a specification on a
1211
- * path that a listing has already answered for — so the listing leaves its mounts
1212
- * here for them. Mounts handed to those functions explicitly always win.
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
- const reportedMounts = /* @__PURE__ */ new Map();
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
- * Remember one listing's mounts.
1217
- * @param sandboxes - the sandboxes the listing reported.
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 recordMounts(sandboxes) {
1220
- for (const sandbox of sandboxes) reportedMounts.set(sandbox.name, sandbox.mounts);
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
- /** The host directory and workspace a reported mount covers, the deepest mount winning. */
1254
- function mountedHostFor(sandboxPath) {
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 mounts of reportedMounts.values()) for (const mount of mounts) {
1257
- const relative = containerRemainder(sandboxPath, mount.sandbox);
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
- const depth = posix.normalize(mount.sandbox).length;
1260
- if (found !== void 0 && found.depth >= depth) continue;
1900
+ if (found !== void 0 && found.length >= mount.host.length) continue;
1901
+ const workspaceRoot = workspaceRootOf(record);
1261
1902
  found = {
1262
- depth,
1263
- root: mount.host,
1264
- host: relative === "" ? normalizeHostRoot(mount.host) : joinHostRoot(mount.host, relative)
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 === void 0 ? void 0 : {
1268
- host: found.host,
1269
- root: found.root
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 = reportedMounts.get(sandboxNameOf(spec));
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
- if (declared !== void 0 && normalizeHostRoot(declared.hostWorkspaceRoot) === root) return asSbxSpec(declared, mounts);
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
- SANDBOX_TEMPLATE,
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, or it has no Node.js.
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} ${SANDBOX_TEMPLATE} ${spec.hostWorkspaceRoot}", 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`);
1481
- if (listed === void 0) await createSandbox(spec, name, run, signal);
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 { variantNameSuffixOf as A, toPosixSlashes as B, presetKindOf as C, VARIANT_KINDS as D, sbxRefusalText as E, isWindowsPath as F, containerOptions as H, joinHostRoot as I, relativeWithinHostRoot as L, hostPathStyle as M, isPathInsideContainer as N, variantIdOf as O, isPosixAbsolute as P, toContainerPath as R, markedVariantKind as S, refusedExecution as T, presetSourceFields as U, containerOptionFields as V, containerPresetOf as _, sandboxNameFor as a, markedContainerOnly as b, sbxWorkspaceRootFor as c, DEVCONTAINER_ENV_KEY as d, DEVCONTAINER_PRESET_ENV_KEY as f, callingVariantKind as g, callingContainerPreset as h, sandboxHostPathFor as i, containerRemainder as j, variantKindOf as k, repoRegistry as l, SBX_PRESET_ENV_KEY as m, bindSbxMount as n, sandboxWorkspacePath as o, SBX_ENV_KEY as p, resolveSbxTarget as r, sbxSpecFor as s, asSbxSpec as t, CONTAINER_MARKER_KEYS as u, fsEscapeRefusalText as v, refusalText as w, markedPreset as x, fsRefusalText as y, toHostPath as z };
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-1GsFjQBk.js.map
2272
+ //# sourceMappingURL=sbx-Blgjzzoe.js.map