@exagone313/dsh-podman 1.6.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/cordis.patch.yml +3 -1
  2. package/dist/approval-reasons.d.ts +37 -0
  3. package/dist/approval-reasons.js +128 -0
  4. package/dist/approval-template-summary.d.ts +8 -0
  5. package/dist/approval-template-summary.js +163 -0
  6. package/dist/approval.d.ts +8 -4
  7. package/dist/approval.js +104 -10
  8. package/dist/client/ContainerCard.js +8 -2
  9. package/dist/client/container-card-controller.d.ts +13 -5
  10. package/dist/client/container-card-controller.js +60 -24
  11. package/dist/client/container-card-create-config.d.ts +23 -0
  12. package/dist/client/container-card-create-config.js +48 -0
  13. package/dist/client/container-card-create-modal.d.ts +9 -1
  14. package/dist/client/container-card-create-modal.js +37 -41
  15. package/dist/client/container-card-create-volume.d.ts +10 -0
  16. package/dist/client/container-card-create-volume.js +34 -0
  17. package/dist/client/container-card-dialog-styles.d.ts +4 -2
  18. package/dist/client/container-card-dialog-styles.js +47 -4
  19. package/dist/client/container-card-edit-modal.d.ts +5 -1
  20. package/dist/client/container-card-edit-modal.js +55 -19
  21. package/dist/client/container-card-editors.d.ts +9 -0
  22. package/dist/client/container-card-editors.js +300 -43
  23. package/dist/client/container-card-form.d.ts +2 -1
  24. package/dist/client/container-card-form.js +26 -8
  25. package/dist/client/container-card-images.js +9 -31
  26. package/dist/client/container-card-mount-actions.d.ts +12 -0
  27. package/dist/client/container-card-mount-actions.js +35 -0
  28. package/dist/client/container-card-mount-sources.d.ts +34 -0
  29. package/dist/client/container-card-mount-sources.js +180 -0
  30. package/dist/client/container-card-names.d.ts +2 -0
  31. package/dist/client/container-card-names.js +12 -0
  32. package/dist/client/container-card-row.d.ts +16 -1
  33. package/dist/client/container-card-row.js +69 -25
  34. package/dist/client/container-card-secrets.d.ts +2 -0
  35. package/dist/client/container-card-secrets.js +60 -17
  36. package/dist/client/container-card-shared.d.ts +17 -9
  37. package/dist/client/container-card-shared.js +122 -93
  38. package/dist/client/container-card-styles.d.ts +6 -0
  39. package/dist/client/container-card-styles.js +22 -0
  40. package/dist/client/container-card-table-styles.d.ts +2 -1
  41. package/dist/client/container-card-table-styles.js +14 -0
  42. package/dist/client/container-card-templates.d.ts +81 -0
  43. package/dist/client/container-card-templates.js +1004 -0
  44. package/dist/client/container-card-toast.js +1 -1
  45. package/dist/client/container-card-volumes.js +6 -20
  46. package/dist/client/container-card-workspace.d.ts +10 -2
  47. package/dist/client/container-card-workspace.js +98 -5
  48. package/dist/client/container-template-ui.d.ts +163 -0
  49. package/dist/client/container-template-ui.js +579 -0
  50. package/dist/client/download.d.ts +1 -0
  51. package/dist/client/download.js +23 -0
  52. package/dist/client/image-facts.d.ts +18 -0
  53. package/dist/client/image-facts.js +44 -0
  54. package/dist/client/index.js +13478 -3438
  55. package/dist/client/locales.d.ts +1 -1
  56. package/dist/client/locales.js +120 -0
  57. package/dist/client/podman-containers.js +47 -18
  58. package/dist/client/podman-terminal-guide.js +4 -2
  59. package/dist/client/podman-terminal.js +4 -2
  60. package/dist/client/template-client.d.ts +9 -0
  61. package/dist/client/template-client.js +52 -0
  62. package/dist/client/template-protocol.d.ts +60 -0
  63. package/dist/client/template-protocol.js +4 -0
  64. package/dist/client/terminal-errors.d.ts +11 -0
  65. package/dist/client/terminal-errors.js +26 -0
  66. package/dist/client/terminal-protocol.d.ts +5 -0
  67. package/dist/client/terminal-protocol.js +5 -0
  68. package/dist/client/terminal-styles.d.ts +2 -1
  69. package/dist/client/terminal-styles.js +9 -1
  70. package/dist/client/terminal-transport.d.ts +17 -2
  71. package/dist/client/terminal-transport.js +31 -8
  72. package/dist/client/tool-presentations.d.ts +32 -0
  73. package/dist/client/tool-presentations.js +33 -0
  74. package/dist/client/tool-views.js +17 -7
  75. package/dist/client/workspace-target.d.ts +54 -0
  76. package/dist/client/workspace-target.js +86 -0
  77. package/dist/container-template.d.ts +153 -0
  78. package/dist/container-template.js +1058 -0
  79. package/dist/generated/version.d.ts +2 -2
  80. package/dist/generated/version.js +2 -2
  81. package/dist/grpc/proto/dshguest/v1/guest.proto +11 -0
  82. package/dist/guest-rpc.d.ts +1 -0
  83. package/dist/guest-rpc.js +12 -0
  84. package/dist/index.js +7 -1
  85. package/dist/mount-enums.d.ts +2 -0
  86. package/dist/mount-enums.js +17 -0
  87. package/dist/mount-order.d.ts +14 -0
  88. package/dist/mount-order.js +49 -0
  89. package/dist/project-path.d.ts +14 -0
  90. package/dist/project-path.js +25 -0
  91. package/dist/template-apply.d.ts +21 -0
  92. package/dist/template-apply.js +102 -0
  93. package/dist/template-files.d.ts +23 -0
  94. package/dist/template-files.js +186 -0
  95. package/dist/template-image.d.ts +22 -0
  96. package/dist/template-image.js +80 -0
  97. package/dist/template-route.d.ts +9 -0
  98. package/dist/template-route.js +278 -0
  99. package/dist/terminal-route.js +49 -7
  100. package/dist/tool-defs.js +27 -1
  101. package/dist/tool-handlers.js +69 -1
  102. package/dist/tool-params.d.ts +38 -0
  103. package/dist/tool-params.js +30 -0
  104. package/docs/README.md +4 -3
  105. package/docs/architecture.md +42 -12
  106. package/docs/architecture.zh.md +22 -8
  107. package/docs/configuration.md +19 -20
  108. package/docs/configuration.zh.md +3 -4
  109. package/docs/development-prompt.md +49 -45
  110. package/docs/development-prompt.zh.md +47 -43
  111. package/docs/development.md +45 -28
  112. package/docs/development.zh.md +59 -46
  113. package/docs/uninstall.md +3 -3
  114. package/docs/uninstall.zh.md +2 -2
  115. package/docs/usage.md +155 -23
  116. package/docs/usage.zh.md +104 -14
  117. package/package.json +34 -33
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "1.6.1";
2
- export declare const GIT_COMMIT = "50e2fb6";
1
+ export declare const VERSION = "1.8.0";
2
+ export declare const GIT_COMMIT = "70dc22c";
@@ -2,5 +2,5 @@
2
2
  //
3
3
  // SPDX-License-Identifier: MIT
4
4
  // Generated by scripts/generate-version.mjs; do not edit.
5
- export const VERSION = "1.6.1";
6
- export const GIT_COMMIT = "50e2fb6";
5
+ export const VERSION = "1.8.0";
6
+ export const GIT_COMMIT = "70dc22c";
@@ -16,6 +16,11 @@ service WorkspaceGuestAgent {
16
16
  rpc Signal(SignalRequest) returns (SignalResponse);
17
17
  rpc ReadFile(ReadFileRequest) returns (stream ReadFileChunk);
18
18
  rpc WriteFile(stream WriteFileChunk) returns (WriteFileResponse);
19
+ // WriteTemplate writes a container template into the project's .dsh-podman
20
+ // directory, creating the directory when it is missing. The name must be a
21
+ // plain basename, and a read-only project mount is reported as a clean
22
+ // permission failure instead of an I/O error.
23
+ rpc WriteTemplate(WriteTemplateRequest) returns (WriteTemplateResponse);
19
24
  rpc Stat(StatRequest) returns (StatResponse);
20
25
  rpc ReadDir(ReadDirRequest) returns (ReadDirResponse);
21
26
  rpc Mkdir(MkdirRequest) returns (MkdirResponse);
@@ -65,6 +70,12 @@ message ReadFileChunk { bytes data = 1; }
65
70
  message WriteFileChunk { oneof payload { WriteFileStart start = 1; bytes data_chunk = 2; } }
66
71
  message WriteFileStart { string path = 1; bool create = 2; bool truncate = 3; }
67
72
  message WriteFileResponse { int64 bytes_written = 1; }
73
+ // WriteTemplateRequest names the project directory, the template name (the
74
+ // file's basename, with or without a .yml/.yaml suffix), and the YAML content.
75
+ message WriteTemplateRequest { string project_dir = 1; string name = 2; bytes content = 3; }
76
+ // WriteTemplateResponse is the path the template was written to, inside the
77
+ // project's .dsh-podman directory.
78
+ message WriteTemplateResponse { string path = 1; }
68
79
  message StatRequest { string path = 1; bool no_follow = 2; }
69
80
  message StatResponse { bool exists = 1; bool is_dir = 2; int64 size = 3; string mode = 4; string modified_at = 5; bool is_symlink = 6; }
70
81
  message ReadDirRequest { string path = 1; }
@@ -25,6 +25,7 @@ export declare function writeGuestFile(binding: WorkspaceBinding, path: string,
25
25
  create: boolean;
26
26
  truncate: boolean;
27
27
  }, signal?: AbortSignal): Promise<number>;
28
+ export declare function writeGuestTemplate(binding: WorkspaceBinding, projectDir: string, name: string, content: string): Promise<string>;
28
29
  export declare function readGuestFile(binding: WorkspaceBinding, path: string): Promise<string>;
29
30
  export interface ExecIdentity {
30
31
  uid?: number;
package/dist/guest-rpc.js CHANGED
@@ -269,6 +269,18 @@ export async function writeGuestFile(binding, path, content, opts, signal) {
269
269
  call.end();
270
270
  }));
271
271
  }
272
+ // writeGuestTemplate asks the guest agent to save a template inside the
273
+ // project's .dsh-podman directory. The plugin's own host-side view of the
274
+ // project is read-only, so the write goes through the container's guest, which
275
+ // creates the directory when missing and refuses a traversing name.
276
+ export async function writeGuestTemplate(binding, projectDir, name, content) {
277
+ const result = (await unaryGuest({ binding }, "writeTemplate", {
278
+ projectDir,
279
+ name,
280
+ content: Buffer.from(content, "utf8"),
281
+ }));
282
+ return typeof result?.path === "string" ? result.path : "";
283
+ }
272
284
  export async function readGuestFile(binding, path) {
273
285
  return withGuestAuth(binding, (guest, token) => new Promise((resolveDone, reject) => {
274
286
  const chunks = [];
package/dist/index.js CHANGED
@@ -5,6 +5,7 @@ import { homedir } from "node:os";
5
5
  import { join } from "node:path";
6
6
  import { isSandboxEscalation, preExecutePolicy, } from "./approval.js";
7
7
  import { resolveReasonLocale } from "./approval-reasons.js";
8
+ import { readTemplateLoadSummary } from "./approval-template-summary.js";
8
9
  import { createFilesystemProvider } from "./fs-provider.js";
9
10
  import { createSpillStore } from "./spill-store.js";
10
11
  import { podmanRuntimeSection, withoutHarnessSourceSection, } from "./prompts.js";
@@ -14,6 +15,7 @@ import { toolHandlers } from "./tool-handlers.js";
14
15
  import { defineTool, TOOL_DESCRIPTIONS, toolOutput, TOOLS, } from "./tool-schemas.js";
15
16
  import { toolCallView, toolResultView } from "./tool-views.js";
16
17
  import { registerCardRoute } from "./card-route.js";
18
+ import { registerTemplateRoute } from "./template-route.js";
17
19
  import { dshVersion } from "./dsh-version.js";
18
20
  import { registerTerminalRoutes } from "./terminal-route.js";
19
21
  import { TerminalSessions } from "./terminal-sessions.js";
@@ -66,7 +68,7 @@ export function apply(ctx, config) {
66
68
  }
67
69
  },
68
70
  }));
69
- ctx.on("tools/pre-execute", (exec, next) => preExecutePolicy(exec, next, () => resolver.getConfig().projectsRoot, () => readLocale(), readSession, readOnlyShellGate()));
71
+ ctx.on("tools/pre-execute", (exec, next) => preExecutePolicy(exec, next, () => resolver.getConfig().projectsRoot, () => readLocale(), readSession, readOnlyShellGate(), (request) => readTemplateLoadSummary(resolver, resolver.getConfig().projectsRoot, request)));
70
72
  // The harness asks the user to widen the sandbox before a confined call (for
71
73
  // example `bash` with `sandbox_permissions`). This deployment bypasses the
72
74
  // sandbox inside the container, so the grant changes nothing: claim the
@@ -122,6 +124,10 @@ export function apply(ctx, config) {
122
124
  // node_modules entry. It is resolved once and served with every snapshot.
123
125
  const dshVersionValue = dshVersion(ctx.get("pluginPackages"));
124
126
  registerCardRoute(ctx, resolver, ctx.workspaceRegistry, readLocale, dshVersionValue);
127
+ // The load-template popup needs structured results (a parsed template, its
128
+ // image plan, apply warnings), so it has its own route rather than riding the
129
+ // card's one-notice command response.
130
+ registerTemplateRoute(ctx, resolver, ctx.workspaceRegistry);
125
131
  // The Podman terminal tab talks to guest ptys through its own routes; the
126
132
  // registry keeps shells alive while the browser is away.
127
133
  const terminalSessions = new TerminalSessions({ resolver });
@@ -1,3 +1,5 @@
1
+ export declare const MOUNT_KIND_ORDER: readonly ["project", "volume", "secret", "tmpfs"];
2
+ export declare function mountKindRank(kind: string): number;
1
3
  export declare function mountKindToProto(kind: string | undefined): string;
2
4
  /**
3
5
  * The mount mode to use when a caller does not name one.
@@ -17,6 +17,23 @@ const KIND_FROM_PROTO = {
17
17
  MOUNT_KIND_VOLUME: "volume",
18
18
  MOUNT_KIND_SECRET: "secret",
19
19
  };
20
+ // The order the container editor's mounts list shows the kinds in: project
21
+ // mounts first, then volumes, secrets and tmpfs. The list further splits
22
+ // projects and volumes by mode, and the container-template renderer uses this
23
+ // kind order alone, keeping the existing sequence within a kind.
24
+ export const MOUNT_KIND_ORDER = [
25
+ "project",
26
+ "volume",
27
+ "secret",
28
+ "tmpfs",
29
+ ];
30
+ // mountKindRank returns a kind's position in MOUNT_KIND_ORDER. An unknown kind
31
+ // sorts last instead of throwing, since callers also rank values decoded from
32
+ // layers this module does not control.
33
+ export function mountKindRank(kind) {
34
+ const index = MOUNT_KIND_ORDER.indexOf(kind);
35
+ return index === -1 ? MOUNT_KIND_ORDER.length : index;
36
+ }
20
37
  // The logical names and the proto enum numbers a mount kind can decode to. A
21
38
  // value reaches a layer in one of several spellings — the enum name with or
22
39
  // without its MOUNT_KIND_ prefix, the short name, or the number a decoder that
@@ -0,0 +1,14 @@
1
+ export declare function isPrimaryProjectMount(mount: {
2
+ kind: string;
3
+ project?: string;
4
+ }, mainProject: string): boolean;
5
+ export interface OrderedMount {
6
+ kind: string;
7
+ project: string;
8
+ destination: string;
9
+ mode: string;
10
+ }
11
+ export declare function orderedMounts<T extends OrderedMount>(mounts: readonly T[], mainProject: string): {
12
+ mount: T;
13
+ index: number;
14
+ }[];
@@ -0,0 +1,49 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ import { mountKindRank } from "./mount-enums.js";
5
+ // Whether a mount is the workspace's primary project mount: a project mount
6
+ // that names the workspace's own project. The container editor lists that mount
7
+ // first and a template exported from the container starts with it, so both read
8
+ // this one predicate rather than each deciding for itself.
9
+ export function isPrimaryProjectMount(mount, mainProject) {
10
+ return mount.kind === "project" && mainProject !== "" &&
11
+ mount.project === mainProject;
12
+ }
13
+ // The category a mount sorts under in an ordered mounts list: the workspace's
14
+ // main project mount first, then read-write projects, read-only projects,
15
+ // read-write volumes, read-only volumes, secrets and tmpfs. The kind order comes
16
+ // from MOUNT_KIND_ORDER, which the template renderer uses too, and the primary
17
+ // project mount is the one predicate both list and export use, so the list and
18
+ // an exported template never disagree on which mount comes first.
19
+ function mountRank(mount, mainProject) {
20
+ if (isPrimaryProjectMount(mount, mainProject))
21
+ return 0;
22
+ const kind = mountKindRank(mount.kind);
23
+ // Only projects and volumes have a mode to split by; a secret and a tmpfs
24
+ // carry one fixed mode, so their single slot leaves a gap that changes
25
+ // nothing.
26
+ const mode = mount.kind === "project" || mount.kind === "volume"
27
+ ? (mount.mode === "read_write" ? 0 : 1)
28
+ : 0;
29
+ return 1 + kind * 2 + mode;
30
+ }
31
+ // The mounts in the one order both the editors and a container block list them
32
+ // in: one category at a time, sorted by mounted path inside the category. Each
33
+ // entry keeps the index it has in the draft, so an edit or a removal still
34
+ // targets the entry behind the row.
35
+ export function orderedMounts(mounts, mainProject) {
36
+ return mounts
37
+ .map((mount, index) => ({ mount, index }))
38
+ .sort((left, right) => {
39
+ const rank = mountRank(left.mount, mainProject) -
40
+ mountRank(right.mount, mainProject);
41
+ if (rank !== 0)
42
+ return rank;
43
+ // A stable sort keeps the draft order inside a category when two mounts
44
+ // share a destination.
45
+ const a = left.mount.destination;
46
+ const b = right.mount.destination;
47
+ return a < b ? -1 : a > b ? 1 : 0;
48
+ });
49
+ }
@@ -1,4 +1,18 @@
1
1
  export declare function projectNameFromHostPath(projectsRoot: string, path: string): string | undefined;
2
+ export type ProjectPathOrigin = "typed" | "browsed";
3
+ export type ProjectPathRejection = "empty" | "absolute" | "escapesRoot" | "missing";
4
+ export type ProjectPathDecision = {
5
+ readonly ok: true;
6
+ readonly project: string;
7
+ } | {
8
+ readonly ok: false;
9
+ readonly reason: ProjectPathRejection;
10
+ };
11
+ export declare function decideProjectPath(check: {
12
+ origin: ProjectPathOrigin;
13
+ project: string;
14
+ directoryExists: boolean;
15
+ }): ProjectPathDecision;
2
16
  export declare function hostPathForProjectName(projectsRoot: string, project: string): string;
3
17
  export declare function confineToRoot(root: string, path: string): string;
4
18
  export declare function parentDirectory(root: string, path: string): string;
@@ -15,6 +15,31 @@ export function projectNameFromHostPath(projectsRoot, path) {
15
15
  return undefined;
16
16
  return target.slice(root.length + 1);
17
17
  }
18
+ // decideProjectPath accepts or refuses a project mount path from its origin,
19
+ // its shape and whether the host reports the directory. It is pure: the caller
20
+ // lists hostPathForProjectName(projectsRoot, project) through the dsh host's
21
+ // directory picker and passes that result as `directoryExists`. A typed value
22
+ // is checked for the same shape the other helpers accept — no absolute path,
23
+ // no ".." above the root — and is normalized once accepted, so the project
24
+ // stored is the one the host path names. A browsed value skips every check:
25
+ // the browser can only yield a directory inside the root it listed.
26
+ export function decideProjectPath(check) {
27
+ const project = String(check.project ?? "");
28
+ if (check.origin === "browsed")
29
+ return { ok: true, project };
30
+ if (project.trim() === "")
31
+ return { ok: false, reason: "empty" };
32
+ if (project.startsWith("/"))
33
+ return { ok: false, reason: "absolute" };
34
+ const name = normalizeProjectPath(project);
35
+ if (name === undefined)
36
+ return { ok: false, reason: "escapesRoot" };
37
+ if (name === "")
38
+ return { ok: false, reason: "empty" };
39
+ if (!check.directoryExists)
40
+ return { ok: false, reason: "missing" };
41
+ return { ok: true, project: name };
42
+ }
18
43
  // hostPathForProjectName is the inverse: the absolute directory a project path
19
44
  // names under the projects root, used to open a directory browser where the
20
45
  // field's current value lives. A value that climbs above the root with ".."
@@ -0,0 +1,21 @@
1
+ import { type ContainerTemplate } from "./container-template.js";
2
+ import type { WorkspaceResolver } from "./workspace-binding.js";
3
+ export interface TemplateApplyOptions {
4
+ workspaceSlug: string;
5
+ projectName: string;
6
+ template: ContainerTemplate;
7
+ imageId: string;
8
+ container?: string;
9
+ }
10
+ export interface TemplateApplyResult {
11
+ row: any;
12
+ container: string;
13
+ warnings: string[];
14
+ }
15
+ export interface TemplatePortsOptions {
16
+ workspaceSlug: string;
17
+ container: string;
18
+ template: ContainerTemplate;
19
+ }
20
+ export declare function applyContainerTemplate(resolver: WorkspaceResolver, options: TemplateApplyOptions): Promise<TemplateApplyResult>;
21
+ export declare function publishTemplatePorts(resolver: WorkspaceResolver, options: TemplatePortsOptions): Promise<string[]>;
@@ -0,0 +1,102 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ // Applying a container template: one create-or-replace request carrying the
5
+ // template's image, environment, secrets, mounts and PATH additions, then the
6
+ // template's ports published after the container exists. The workspace's own
7
+ // project mount is always added, so a loaded template can never lock the
8
+ // session out of its own project; the template chooses its mode when it declares
9
+ // the mount, and it is read-write only when the template omits it.
10
+ //
11
+ // A workspace with no container gets its default container created. An existing
12
+ // container is replaced through StartContainer: the mounts it is given replace
13
+ // the current ones, the environment, secret environment and PATH additions the
14
+ // template declares replace those groups, groups it leaves undeclared keep their
15
+ // values, and published ports are kept.
16
+ import { templateMountInputs, } from "./container-template.js";
17
+ import { grpc } from "./grpc/runtime-client.js";
18
+ import { mountInputToProto } from "./mount-input.js";
19
+ import { portProtocolToProto } from "./publish-port.js";
20
+ // applyContainerTemplate runs the one create path the load popup and the
21
+ // template load tool share.
22
+ export async function applyContainerTemplate(resolver, options) {
23
+ const { template } = options;
24
+ const projectsRoot = resolver.getConfig().projectsRoot;
25
+ const mounts = templateMountInputs(template, options.projectName).map((mount) => mountInputToProto(mount, projectsRoot));
26
+ const payload = {
27
+ workspaceSlug: options.workspaceSlug,
28
+ imageId: options.imageId,
29
+ };
30
+ if (mounts.length > 0)
31
+ payload.mounts = mounts;
32
+ if (Object.keys(template.spec.env).length > 0) {
33
+ payload.env = template.spec.env;
34
+ }
35
+ if (Object.keys(template.spec.secretEnv).length > 0) {
36
+ payload.secretEnv = template.spec.secretEnv;
37
+ }
38
+ if (template.spec.paths.length > 0)
39
+ payload.paths = template.spec.paths;
40
+ const target = options.container ?? "default";
41
+ const exists = await workspaceExists(resolver, options.workspaceSlug);
42
+ let row;
43
+ if (!exists) {
44
+ if (target !== "default") {
45
+ throw new Error(`workspace ${JSON.stringify(options.workspaceSlug)} has no container yet: load the template without a container name to create its default container`);
46
+ }
47
+ row = await resolver.control("createWorkspace", {
48
+ ...payload,
49
+ projectName: options.projectName,
50
+ });
51
+ }
52
+ else {
53
+ // StartContainer replaces an existing container in place: the payload's
54
+ // mounts and declared groups replace the current ones and published ports
55
+ // are kept.
56
+ row = await resolver.control("startContainer", {
57
+ ...payload,
58
+ container: target,
59
+ });
60
+ }
61
+ const warnings = await publishTemplatePorts(resolver, {
62
+ workspaceSlug: options.workspaceSlug,
63
+ container: target,
64
+ template,
65
+ });
66
+ return { row, container: target, warnings };
67
+ }
68
+ // publishTemplatePorts publishes every port a template declares on an existing
69
+ // container. It is what a template-sourced replace does after the edit editor's
70
+ // Apply succeeded; a port the gateway refuses is a warning, never a failure.
71
+ export async function publishTemplatePorts(resolver, options) {
72
+ const warnings = [];
73
+ for (const port of options.template.spec.ports) {
74
+ const request = {
75
+ workspaceSlug: options.workspaceSlug,
76
+ container: options.container,
77
+ port: port.container,
78
+ protocol: portProtocolToProto("tcp"),
79
+ };
80
+ if (port.host !== undefined)
81
+ request.suggestedHostPort = port.host;
82
+ try {
83
+ await resolver.control("publishPort", request);
84
+ }
85
+ catch (error) {
86
+ warnings.push(`port ${port.container}/tcp: ${error instanceof Error ? error.message : String(error)}`);
87
+ }
88
+ }
89
+ return warnings;
90
+ }
91
+ async function workspaceExists(resolver, slug) {
92
+ try {
93
+ await resolver.control("describeWorkspace", { workspaceSlug: slug });
94
+ return true;
95
+ }
96
+ catch (error) {
97
+ if (error?.code === grpc.status.NOT_FOUND) {
98
+ return false;
99
+ }
100
+ throw error;
101
+ }
102
+ }
@@ -0,0 +1,23 @@
1
+ export declare const MAX_TEMPLATE_BYTES: number;
2
+ export interface ProjectTemplateFile {
3
+ name: string;
4
+ path: string;
5
+ yaml: string;
6
+ }
7
+ export declare class TemplateFileError extends Error {
8
+ constructor(message: string);
9
+ }
10
+ export declare function templateFileName(name: unknown): string;
11
+ export declare function templateDisplayName(name: string): string;
12
+ export declare function templateDirectory(projectPath: string): string;
13
+ export declare function templatePathForName(projectPath: string, name: unknown): string;
14
+ export declare function listProjectTemplates(projectPath: string): Promise<ProjectTemplateFile[]>;
15
+ export declare function readProjectTemplate(projectPath: string, name: unknown): Promise<ProjectTemplateFile>;
16
+ export declare function projectDirectoryExists(projectsRoot: string, project: string): Promise<boolean>;
17
+ export declare function workspaceForCwd(registry: any, projectsRoot: string, cwd: unknown): Promise<RegisteredWorkspace>;
18
+ export interface RegisteredWorkspace {
19
+ workspaceSlug: string;
20
+ projectName: string;
21
+ projectPath: string;
22
+ }
23
+ export declare function workspaceForSlug(registry: any, projectsRoot: string, slug: string): RegisteredWorkspace;
@@ -0,0 +1,186 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ // Reading a project's container templates on the dsh host. The host-side
5
+ // project view is read-only (the dsh container mounts the projects root that
6
+ // way), so this module only lists and reads; saving goes through the guest
7
+ // write RPC. It is the file half of the same host listing the workspace
8
+ // directory picker uses: no orchestrator call and no container is involved.
9
+ import { readdir, readFile, stat } from "node:fs/promises";
10
+ import { join } from "node:path";
11
+ import { normalizeProjectPath, TEMPLATE_DIRECTORY, TEMPLATE_EXTENSION, } from "./container-template.js";
12
+ import { projectNameFromHostPath } from "./project-path.js";
13
+ import { workspaceSlug } from "./workspace-binding.js";
14
+ // A template larger than this is refused rather than read into memory: a
15
+ // template is a small configuration document.
16
+ export const MAX_TEMPLATE_BYTES = 1 << 20;
17
+ export class TemplateFileError extends Error {
18
+ constructor(message) {
19
+ super(message);
20
+ this.name = "TemplateFileError";
21
+ }
22
+ }
23
+ // templateFileName validates a template name as one plain basename and returns
24
+ // the file name to read or write. A name without a YAML suffix gets the
25
+ // canonical ".yml" one; a name with one keeps it. Traversal, hidden files and
26
+ // separators are refused here, so every caller shares the rule (the guest agent
27
+ // enforces the same one).
28
+ export function templateFileName(name) {
29
+ if (typeof name !== "string" || name === "") {
30
+ throw new TemplateFileError("template name is required");
31
+ }
32
+ if (name.length > 200) {
33
+ throw new TemplateFileError(`template name ${JSON.stringify(name)} is too long`);
34
+ }
35
+ if (/[/\\\0\n\r]/.test(name)) {
36
+ throw new TemplateFileError(`template name ${JSON.stringify(name)} must be a plain basename with no path separators`);
37
+ }
38
+ if (name === "." || name === ".." || name.startsWith(".")) {
39
+ throw new TemplateFileError(`template name ${JSON.stringify(name)} must be a plain basename`);
40
+ }
41
+ return /\.(?:ya?ml)$/i.test(name) ? name : `${name}${TEMPLATE_EXTENSION}`;
42
+ }
43
+ // templateDisplayName drops the YAML suffix, the name a popup shows.
44
+ export function templateDisplayName(name) {
45
+ return name.replace(/\.(?:ya?ml)$/i, "");
46
+ }
47
+ // templateDirectory is the directory templates live in, below a project root.
48
+ export function templateDirectory(projectPath) {
49
+ return join(projectPath, TEMPLATE_DIRECTORY);
50
+ }
51
+ // templatePathForName resolves a template name to the absolute path it reads
52
+ // from and the guest RPC writes to. The name was already reduced to one
53
+ // basename, so the join cannot escape the template directory.
54
+ export function templatePathForName(projectPath, name) {
55
+ return join(templateDirectory(projectPath), templateFileName(name));
56
+ }
57
+ // listProjectTemplates lists the readable YAML templates of one project,
58
+ // sorted by file name. A missing .dsh-podman directory is an empty list, not an
59
+ // error: no template was saved yet. Directories, hidden files and symlinks are
60
+ // skipped, so listing never follows a link out of the project.
61
+ export async function listProjectTemplates(projectPath) {
62
+ const directory = templateDirectory(projectPath);
63
+ let entries;
64
+ try {
65
+ entries = await readdir(directory, { withFileTypes: true });
66
+ }
67
+ catch (error) {
68
+ if (isMissing(error))
69
+ return [];
70
+ throw new TemplateFileError(`cannot list ${directory}: ${errorMessage(error)}`);
71
+ }
72
+ const names = entries
73
+ .filter((entry) => entry.isFile() && !entry.name.startsWith(".") &&
74
+ /\.(?:ya?ml)$/i.test(entry.name))
75
+ .map((entry) => entry.name)
76
+ .sort((left, right) => left.localeCompare(right));
77
+ const templates = [];
78
+ for (const name of names) {
79
+ const path = join(directory, name);
80
+ try {
81
+ const info = await stat(path);
82
+ if (!info.isFile() || info.size > MAX_TEMPLATE_BYTES)
83
+ continue;
84
+ templates.push({
85
+ name,
86
+ path,
87
+ yaml: await readFile(path, "utf8"),
88
+ });
89
+ }
90
+ catch {
91
+ // An entry that vanished or cannot be read is skipped; the listing still
92
+ // serves every other template.
93
+ }
94
+ }
95
+ return templates;
96
+ }
97
+ // readProjectTemplate reads one named template, refusing anything but a
98
+ // regular, bounded file.
99
+ export async function readProjectTemplate(projectPath, name) {
100
+ const file = templateFileName(name);
101
+ const path = join(templateDirectory(projectPath), file);
102
+ let info;
103
+ try {
104
+ info = await stat(path);
105
+ }
106
+ catch (error) {
107
+ if (isMissing(error)) {
108
+ throw new TemplateFileError(`template ${JSON.stringify(file)} not found in ${TEMPLATE_DIRECTORY}`);
109
+ }
110
+ throw new TemplateFileError(`cannot read template ${JSON.stringify(file)}: ${errorMessage(error)}`);
111
+ }
112
+ if (!info.isFile()) {
113
+ throw new TemplateFileError(`template ${JSON.stringify(file)} is not a regular file`);
114
+ }
115
+ if (info.size > MAX_TEMPLATE_BYTES) {
116
+ throw new TemplateFileError(`template ${JSON.stringify(file)} is too large`);
117
+ }
118
+ return { name: file, path, yaml: await readFile(path, "utf8") };
119
+ }
120
+ // projectDirectoryExists reports whether a project path names an existing
121
+ // directory under the projects root. It is the check behind the load popup's
122
+ // warning about a project mount whose directory was removed.
123
+ export async function projectDirectoryExists(projectsRoot, project) {
124
+ const name = normalizeProjectPath(project);
125
+ if (name === undefined)
126
+ return false;
127
+ const root = projectsRoot.replace(/\/+$/, "");
128
+ if (root === "")
129
+ return false;
130
+ const path = join(root, name);
131
+ if (path !== `${root}/${name}`)
132
+ return false;
133
+ try {
134
+ return (await stat(path)).isDirectory();
135
+ }
136
+ catch {
137
+ return false;
138
+ }
139
+ }
140
+ // workspaceForCwd resolves the dsh workspace that owns a session working
141
+ // directory, the same lookup the tools and the terminal use.
142
+ export async function workspaceForCwd(registry, projectsRoot, cwd) {
143
+ if (typeof cwd !== "string" || cwd === "") {
144
+ throw new TemplateFileError(`cannot resolve a workspace without a session working directory (got ${JSON.stringify(cwd)})`);
145
+ }
146
+ const workspace = await registry?.resolveByPath?.(cwd);
147
+ if (workspace === undefined) {
148
+ throw new TemplateFileError(`no workspace owns session directory ${JSON.stringify(cwd)}`);
149
+ }
150
+ const projectPath = String(workspace.path ?? "");
151
+ const projectName = projectNameFromHostPath(projectsRoot, projectPath);
152
+ if (projectName === undefined) {
153
+ throw new TemplateFileError(`workspace ${JSON.stringify(workspaceSlug(workspace.id))} is not under the projects root`);
154
+ }
155
+ return {
156
+ workspaceSlug: workspaceSlug(workspace.id),
157
+ projectName,
158
+ projectPath,
159
+ };
160
+ }
161
+ // workspaceForSlug resolves a registered dsh workspace by its slug. The project
162
+ // name is its path relative to the projects root, which is the value a project
163
+ // mount stores; a workspace outside the root is refused rather than mounted
164
+ // with an absolute name.
165
+ export function workspaceForSlug(registry, projectsRoot, slug) {
166
+ if (slug === "")
167
+ throw new TemplateFileError("a workspace is required");
168
+ for (const workspace of registry?.list?.() ?? []) {
169
+ if (workspaceSlug(workspace.id) !== slug)
170
+ continue;
171
+ const projectPath = String(workspace.path ?? "");
172
+ const projectName = projectNameFromHostPath(projectsRoot, projectPath);
173
+ if (projectName === undefined) {
174
+ throw new TemplateFileError(`workspace ${JSON.stringify(slug)} is not under the projects root`);
175
+ }
176
+ return { workspaceSlug: slug, projectName, projectPath };
177
+ }
178
+ throw new TemplateFileError(`unknown workspace ${JSON.stringify(slug)}`);
179
+ }
180
+ function isMissing(error) {
181
+ const code = error?.code;
182
+ return code === "ENOENT" || code === "ENOTDIR";
183
+ }
184
+ function errorMessage(error) {
185
+ return error instanceof Error ? error.message : String(error);
186
+ }
@@ -0,0 +1,22 @@
1
+ import { type ContainerTemplate, type TemplateImagePlan } from "./container-template.js";
2
+ import type { WorkspaceResolver } from "./workspace-binding.js";
3
+ export interface TemplateImageResult {
4
+ imageId: string;
5
+ plan: TemplateImagePlan;
6
+ built: boolean;
7
+ removed: boolean;
8
+ supersededImageId?: string;
9
+ }
10
+ export declare function ensureTemplateImage(resolver: WorkspaceResolver, options: {
11
+ name: string;
12
+ path: string;
13
+ template: ContainerTemplate;
14
+ force?: boolean;
15
+ images?: readonly {
16
+ imageId: string;
17
+ parent: string;
18
+ packages: readonly string[];
19
+ status?: string;
20
+ basePublic?: boolean;
21
+ }[];
22
+ }): Promise<TemplateImageResult>;