@exagone313/dsh-podman 1.7.0 → 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 +6 -5
@@ -2,6 +2,19 @@ import { type TerminalControl, type TerminalFrame, type TerminalOpenQuery, type
2
2
  export type TerminalStreamQuery = TerminalOpenQuery & {
3
3
  readonly reopen?: boolean;
4
4
  };
5
+ /** Options of one session-workspace read. */
6
+ export interface FetchTerminalTargetOptions {
7
+ /**
8
+ * How long the host may wait for the session's workspace to register, in
9
+ * milliseconds. Omitted means the host answers at once.
10
+ */
11
+ readonly waitMs?: number;
12
+ }
13
+ /**
14
+ * The short wait a terminal pane grants a page load to restore its session's
15
+ * workspace, so a tab opened during that window resolves instead of failing.
16
+ */
17
+ export declare const TERMINAL_TARGET_READY_WAIT_MS = 1000;
5
18
  /**
6
19
  * Open or reattach one terminal and deliver every frame to `onFrame`.
7
20
  *
@@ -38,10 +51,12 @@ export declare function fetchTerminalShells(workspace: string, container: string
38
51
  * the session itself and reports when it cannot place it.
39
52
  * @param sessionId - owning session.
40
53
  * @param signal - cancellation of the read.
54
+ * @param options - how long the host may wait for the workspace to register.
41
55
  * @returns the resolved workspace and its harness workspace slug.
42
- * @throws when the host cannot determine the session's workspace.
56
+ * @throws when the host cannot determine the session's workspace, with a
57
+ * `WorkspacePendingError` while that is only a matter of waiting.
43
58
  */
44
- export declare function fetchTerminalTarget(sessionId: string, signal?: AbortSignal): Promise<TerminalTargetView>;
59
+ export declare function fetchTerminalTarget(sessionId: string, signal?: AbortSignal, options?: FetchTerminalTargetOptions): Promise<TerminalTargetView>;
45
60
  /**
46
61
  * List the terminals this session still has retained on the host.
47
62
  * @param sessionId - owning session.
@@ -5,21 +5,38 @@
5
5
  // same-origin `fetch` on the harness API channel, which carries the browser
6
6
  // session the harness issued for it; no service is injected here so the module
7
7
  // stays testable and usable from any component.
8
- import { TERMINAL_PATH, TERMINAL_RETAINED_PATH, TERMINAL_SHELLS_PATH, TERMINAL_TARGET_PATH, } from "./terminal-protocol.js";
8
+ import { WorkspacePendingError } from "./terminal-errors.js";
9
+ import { TERMINAL_PATH, TERMINAL_RETAINED_PATH, TERMINAL_SHELLS_PATH, TERMINAL_TARGET_PATH, WORKSPACE_PENDING_CODE, } from "./terminal-protocol.js";
10
+ /**
11
+ * The short wait a terminal pane grants a page load to restore its session's
12
+ * workspace, so a tab opened during that window resolves instead of failing.
13
+ */
14
+ export const TERMINAL_TARGET_READY_WAIT_MS = 1_000;
15
+ // The host's read is cheap, so a failed parse falls back to the status text.
9
16
  async function failure(response) {
17
+ let body = {};
10
18
  try {
11
- const body = (await response.json());
12
- if (typeof body.error === "string" && body.error !== "") {
13
- return new Error(body.error);
14
- }
19
+ body = (await response.json());
15
20
  }
16
21
  catch {
17
22
  // A non-JSON body falls through to the status text.
18
23
  }
24
+ // The target route's pending answer is retryable, so it keeps its code; every
25
+ // other refusal stays a plain error.
26
+ if (response.status === 409 && body.code === WORKSPACE_PENDING_CODE) {
27
+ return new WorkspacePendingError(typeof body.error === "string" && body.error !== "" ? body.error : "");
28
+ }
29
+ if (typeof body.error === "string" && body.error !== "") {
30
+ return new Error(body.error);
31
+ }
19
32
  return new Error(`terminal request failed (${response.status})`);
20
33
  }
21
34
  function endpoint(path) {
22
- return new URL(path, globalThis.location.origin);
35
+ // The browser always provides `location`; the fallback keeps this module
36
+ // importable from the host test program, which has no DOM lib.
37
+ const origin = globalThis.location
38
+ ?.origin ?? "http://localhost";
39
+ return new URL(path, origin);
23
40
  }
24
41
  function trimmed(value) {
25
42
  return typeof value === "string" ? value : "";
@@ -133,12 +150,18 @@ export async function fetchTerminalShells(workspace, container, sessionId, signa
133
150
  * the session itself and reports when it cannot place it.
134
151
  * @param sessionId - owning session.
135
152
  * @param signal - cancellation of the read.
153
+ * @param options - how long the host may wait for the workspace to register.
136
154
  * @returns the resolved workspace and its harness workspace slug.
137
- * @throws when the host cannot determine the session's workspace.
155
+ * @throws when the host cannot determine the session's workspace, with a
156
+ * `WorkspacePendingError` while that is only a matter of waiting.
138
157
  */
139
- export async function fetchTerminalTarget(sessionId, signal) {
158
+ export async function fetchTerminalTarget(sessionId, signal, options = {}) {
140
159
  const url = endpoint(TERMINAL_TARGET_PATH);
141
160
  url.searchParams.set("sessionId", sessionId);
161
+ const waitMs = options.waitMs;
162
+ if (typeof waitMs === "number" && Number.isFinite(waitMs) && waitMs > 0) {
163
+ url.searchParams.set("wait", String(Math.floor(waitMs)));
164
+ }
142
165
  const response = await fetch(url, {
143
166
  headers: { accept: "application/json" },
144
167
  signal,
@@ -2,6 +2,13 @@ import type { ContainerPluginKey } from "./locales.js";
2
2
  export interface ToolPresentation {
3
3
  readonly titleKey: ContainerPluginKey;
4
4
  readonly summaryKeys: readonly string[];
5
+ /**
6
+ * The fence language when the tool's result is source text to show verbatim
7
+ * (a template YAML document), rather than a status or a JSON payload. The row
8
+ * renders it as a code block — real line breaks, selectable, with a copy
9
+ * control — instead of the raw quoted result string.
10
+ */
11
+ readonly resultFence?: string;
5
12
  }
6
13
  export declare const TOOL_PRESENTATION: {
7
14
  readonly container_bash: {
@@ -36,6 +43,19 @@ export declare const TOOL_PRESENTATION: {
36
43
  readonly titleKey: "toolTitle_container_list";
37
44
  readonly summaryKeys: readonly [];
38
45
  };
46
+ readonly container_template_load: {
47
+ readonly titleKey: "toolTitle_container_template_load";
48
+ readonly summaryKeys: readonly ["template", "container"];
49
+ };
50
+ readonly container_template_export: {
51
+ readonly titleKey: "toolTitle_container_template_export";
52
+ readonly summaryKeys: readonly ["container"];
53
+ readonly resultFence: "yaml";
54
+ };
55
+ readonly container_template_save: {
56
+ readonly titleKey: "toolTitle_container_template_save";
57
+ readonly summaryKeys: readonly ["name"];
58
+ };
39
59
  readonly container_start: {
40
60
  readonly titleKey: "toolTitle_container_start";
41
61
  readonly summaryKeys: readonly ["container", "image"];
@@ -165,3 +185,15 @@ export declare const TOOL_PRESENTATION: {
165
185
  export declare const TOOL_VIEW_KEYS: readonly string[];
166
186
  /** The presentation of one tool, or undefined when this package has no row. */
167
187
  export declare function toolPresentation(name: string): ToolPresentation | undefined;
188
+ /** The source text a fenced result renders, with its fence language. */
189
+ export interface ToolResultCode {
190
+ readonly lang: string;
191
+ readonly code: string;
192
+ }
193
+ /**
194
+ * The code block a tool's result presents as, or null when the tool declares no
195
+ * fenced result. A string-returning tool's model-facing result is the
196
+ * JSON-encoded scalar, so decode that envelope before rendering the source;
197
+ * any other payload stays verbatim.
198
+ */
199
+ export declare function toolResultCode(name: string, text: string | null): ToolResultCode | null;
@@ -34,6 +34,19 @@ export const TOOL_PRESENTATION = {
34
34
  titleKey: "toolTitle_container_list",
35
35
  summaryKeys: [],
36
36
  },
37
+ container_template_load: {
38
+ titleKey: "toolTitle_container_template_load",
39
+ summaryKeys: ["template", "container"],
40
+ },
41
+ container_template_export: {
42
+ titleKey: "toolTitle_container_template_export",
43
+ summaryKeys: ["container"],
44
+ resultFence: "yaml",
45
+ },
46
+ container_template_save: {
47
+ titleKey: "toolTitle_container_template_save",
48
+ summaryKeys: ["name"],
49
+ },
37
50
  container_start: {
38
51
  titleKey: "toolTitle_container_start",
39
52
  summaryKeys: ["container", "image"],
@@ -165,3 +178,23 @@ export const TOOL_VIEW_KEYS = Object.keys(TOOL_PRESENTATION);
165
178
  export function toolPresentation(name) {
166
179
  return TOOL_PRESENTATION[name];
167
180
  }
181
+ /**
182
+ * The code block a tool's result presents as, or null when the tool declares no
183
+ * fenced result. A string-returning tool's model-facing result is the
184
+ * JSON-encoded scalar, so decode that envelope before rendering the source;
185
+ * any other payload stays verbatim.
186
+ */
187
+ export function toolResultCode(name, text) {
188
+ const lang = toolPresentation(name)?.resultFence;
189
+ if (lang === undefined || text === null)
190
+ return null;
191
+ try {
192
+ const value = JSON.parse(text);
193
+ if (typeof value === "string")
194
+ return { lang, code: value };
195
+ }
196
+ catch {
197
+ // Not JSON: the result is already the source text.
198
+ }
199
+ return { lang, code: text };
200
+ }
@@ -3,10 +3,10 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
3
3
  //
4
4
  // SPDX-License-Identifier: MIT
5
5
  import { useState } from "react";
6
- import { DisclosureRow, IconApiOutlineRegular, IconArchiveOutlineRegular, IconBrowseOutlineRegular, IconDataOutlineRegular, IconEditOutlineRegular, IconFolderOpenOutlineRegular, IconLinkOutlineRegular, IconPlayOutlineRegular, IconPlusOutlineRegular, IconRefreshOutlineRegular, IconSearchOutlineRegular, IconSparkleRegular, IconStopFillRegular, IconTrashOutlineRegular, StateDot, TerminalBlock, } from "@deepseek-ai/dsh-client-ui-primitives";
7
- import { toolPresentation } from "./tool-presentations.js";
6
+ import { CodeBlock, DisclosureRow, IconApiOutlineRegular, IconArchiveOutlineRegular, IconBrowseOutlineRegular, IconDataOutlineRegular, IconEditOutlineRegular, IconFolderOpenOutlineRegular, IconLinkOutlineRegular, IconPlayOutlineRegular, IconPlusOutlineRegular, IconRefreshOutlineRegular, IconSearchOutlineRegular, IconSparkleRegular, IconStopFillRegular, IconTrashOutlineRegular, StateDot, TerminalBlock, } from "@deepseek-ai/dsh-client-ui-primitives";
7
+ import { toolPresentation, toolResultCode, } from "./tool-presentations.js";
8
8
  export { TOOL_VIEW_KEYS } from "./tool-presentations.js";
9
- import { TERMINAL_CLASS } from "./terminal-styles.js";
9
+ import { CODE_BLOCK_CLASS, TERMINAL_CLASS } from "./terminal-styles.js";
10
10
  // A domain-owned row for every podman tool, registered over the keyed
11
11
  // `tool.call.toolview` slot. Without it the shipped client renders each call as
12
12
  // "Tool call · <tool name>"; this row owns the icon, title, summary and body.
@@ -21,6 +21,9 @@ const TOOL_ICONS = {
21
21
  container_glob: _jsx(IconSearchOutlineRegular, { size: 14 }),
22
22
  container_grep: _jsx(IconSearchOutlineRegular, { size: 14 }),
23
23
  container_list: _jsx(IconDataOutlineRegular, { size: 14 }),
24
+ container_template_load: _jsx(IconFolderOpenOutlineRegular, { size: 14 }),
25
+ container_template_export: _jsx(IconArchiveOutlineRegular, { size: 14 }),
26
+ container_template_save: _jsx(IconEditOutlineRegular, { size: 14 }),
24
27
  container_start: _jsx(IconPlayOutlineRegular, { size: 14 }),
25
28
  container_recreate: _jsx(IconRefreshOutlineRegular, { size: 14 }),
26
29
  container_remove: _jsx(IconTrashOutlineRegular, { size: 14 }),
@@ -249,13 +252,18 @@ export function PodmanToolRow({ toolName, block, cwd, home, inspect, t, }) {
249
252
  ? "error"
250
253
  : "done";
251
254
  const output = prettyOutput(resultText(block));
255
+ // A declared fenced result is source text, shown as a syntax-highlighted
256
+ // code block rather than the quoted JSON scalar the raw result carries.
257
+ // Failures keep the generic error body.
258
+ const code = state === "done" ? toolResultCode(toolName, output) : null;
252
259
  const failureLine = state === "error" && output !== null && output !== ""
253
260
  ? firstLine(output)
254
261
  : null;
255
262
  const summary = failureLine ??
256
263
  argSummary(args, presentation?.summaryKeys ?? [], firstLine(argsRaw) || block.callId);
257
264
  const [expanded, setExpanded] = useState(false);
258
- const expandable = terminal !== null || (output !== null && output !== "");
265
+ const expandable = terminal !== null || code !== null ||
266
+ (output !== null && output !== "");
259
267
  const leading = state === "error"
260
268
  ? _jsx(StateDot, { state: "error" })
261
269
  : state === "stopped"
@@ -266,7 +274,9 @@ export function PodmanToolRow({ toolName, block, cwd, home, inspect, t, }) {
266
274
  void inspect;
267
275
  return (_jsx(DisclosureRow, { icon: leading, title: title, open: expanded && expandable, expandable: expandable, onToggle: () => setExpanded((value) => !value), expandOnRowClick: true, keepContentWhenOpen: true, collapsedContent: _jsxs(_Fragment, { children: [_jsx("span", { style: sepStyle, "aria-hidden": true }), _jsx("span", { style: failureLine !== null ? errorSummaryStyle : summaryStyle, children: summary })] }), children: terminal !== null
268
276
  ? (_jsx(TerminalBlock, { command: terminal.command, cwd: terminal.cwd, home: home, output: terminal.output, exitCode: terminal.exitCode, signal: terminal.signal, running: terminal.running, maxLines: MAX_RENDERED_LINES, className: TERMINAL_CLASS, labels: terminalLabels(t) }))
269
- : expandable
270
- ? (_jsx("pre", { style: state === "error" ? errorBodyStyle : bodyStyle, children: capLines(output ?? "", MAX_RENDERED_LINES) }))
271
- : null }));
277
+ : code !== null
278
+ ? (_jsx(CodeBlock, { code: code.code, lang: code.lang, className: CODE_BLOCK_CLASS, copyLabel: t("copy"), copiedLabel: t("copied") }))
279
+ : expandable
280
+ ? (_jsx("pre", { style: state === "error" ? errorBodyStyle : bodyStyle, children: capLines(output ?? "", MAX_RENDERED_LINES) }))
281
+ : null }));
272
282
  }
@@ -0,0 +1,54 @@
1
+ import type { TerminalTargetView } from "./terminal-protocol.js";
2
+ /** How long each target request waits on the host before reporting pending. */
3
+ export declare const WORKSPACE_TARGET_WAIT_MS = 1000;
4
+ /** First backoff delay between target requests. */
5
+ export declare const WORKSPACE_RETRY_INITIAL_DELAY_MS = 250;
6
+ /** Longest backoff delay between target requests. */
7
+ export declare const WORKSPACE_RETRY_MAX_DELAY_MS = 2000;
8
+ /** Total time the pane keeps retrying a pending workspace before asking. */
9
+ export declare const WORKSPACE_RETRY_BUDGET_MS = 15000;
10
+ /**
11
+ * The delay before one retry, or undefined once the budget is spent.
12
+ *
13
+ * The first retry waits 250 ms, then each doubles up to 2 s. A delay never
14
+ * runs past the remaining budget, so the pane stops close to 15 s.
15
+ * @param attempt - zero-based retry number.
16
+ * @param elapsedMs - time spent since the first request.
17
+ * @returns the delay in milliseconds, or undefined to stop retrying.
18
+ */
19
+ export declare function workspaceRetryDelay(attempt: number, elapsedMs: number): number | undefined;
20
+ /** What waiting for the Session workspace settled on. */
21
+ export type WorkspaceTargetResult = {
22
+ readonly status: "ready";
23
+ readonly target: TerminalTargetView;
24
+ } | {
25
+ readonly status: "pending";
26
+ } | {
27
+ readonly status: "failed";
28
+ readonly error: unknown;
29
+ } | {
30
+ readonly status: "aborted";
31
+ };
32
+ /** Inputs of {@link waitForWorkspaceTarget}. */
33
+ export interface WorkspaceTargetOptions {
34
+ /** One target read; rejects with a pending error while the workspace starts. */
35
+ readonly fetchTarget: (signal: AbortSignal) => Promise<TerminalTargetView>;
36
+ /** Cancels the loop, its sleep and any state update the caller makes. */
37
+ readonly signal: AbortSignal;
38
+ /** Test seam: the delay implementation. Defaults to an abortable timer. */
39
+ readonly sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>;
40
+ /** Test seam: the clock. Defaults to `Date.now`. */
41
+ readonly now?: () => number;
42
+ }
43
+ /**
44
+ * Read the Session workspace, retrying the host's pending answer.
45
+ *
46
+ * The first request carries a short wait. A pending answer is retried with a
47
+ * capped exponential backoff for about 15 s; any other failure stops at once.
48
+ * Aborting resolves `aborted`, and the sleep is cut short so no timer outlives
49
+ * the pane.
50
+ * @param options - the request, its lifetime and the test seams.
51
+ * @returns the resolved target, the exhausted pending wait, the real failure or
52
+ * the abort.
53
+ */
54
+ export declare function waitForWorkspaceTarget(options: WorkspaceTargetOptions): Promise<WorkspaceTargetResult>;
@@ -0,0 +1,86 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ // The Containers tab's wait for the Session workspace. A page load, a restored
5
+ // tab and a newly created Session can all ask the host before its workspace has
6
+ // registered; the route then answers `workspace-pending` instead of refusing.
7
+ // This module owns the retry policy: a short wait per request, then a capped
8
+ // exponential backoff inside one total budget, after which the pane offers a
9
+ // manual retry rather than showing a hard error.
10
+ //
11
+ // Everything here is environment-free: timers and the clock are injectable so
12
+ // the loop can be driven by the host test program.
13
+ import { isWorkspacePendingError } from "./terminal-errors.js";
14
+ /** How long each target request waits on the host before reporting pending. */
15
+ export const WORKSPACE_TARGET_WAIT_MS = 1_000;
16
+ /** First backoff delay between target requests. */
17
+ export const WORKSPACE_RETRY_INITIAL_DELAY_MS = 250;
18
+ /** Longest backoff delay between target requests. */
19
+ export const WORKSPACE_RETRY_MAX_DELAY_MS = 2_000;
20
+ /** Total time the pane keeps retrying a pending workspace before asking. */
21
+ export const WORKSPACE_RETRY_BUDGET_MS = 15_000;
22
+ /**
23
+ * The delay before one retry, or undefined once the budget is spent.
24
+ *
25
+ * The first retry waits 250 ms, then each doubles up to 2 s. A delay never
26
+ * runs past the remaining budget, so the pane stops close to 15 s.
27
+ * @param attempt - zero-based retry number.
28
+ * @param elapsedMs - time spent since the first request.
29
+ * @returns the delay in milliseconds, or undefined to stop retrying.
30
+ */
31
+ export function workspaceRetryDelay(attempt, elapsedMs) {
32
+ if (elapsedMs >= WORKSPACE_RETRY_BUDGET_MS)
33
+ return undefined;
34
+ const nominal = Math.min(WORKSPACE_RETRY_INITIAL_DELAY_MS * 2 ** attempt, WORKSPACE_RETRY_MAX_DELAY_MS);
35
+ return Math.min(nominal, WORKSPACE_RETRY_BUDGET_MS - elapsedMs);
36
+ }
37
+ function abortableSleep(delayMs, signal) {
38
+ if (signal.aborted || delayMs <= 0)
39
+ return Promise.resolve();
40
+ return new Promise((resolve) => {
41
+ const timer = setTimeout(done, delayMs);
42
+ function done() {
43
+ clearTimeout(timer);
44
+ signal.removeEventListener("abort", done);
45
+ resolve();
46
+ }
47
+ signal.addEventListener("abort", done, { once: true });
48
+ });
49
+ }
50
+ /**
51
+ * Read the Session workspace, retrying the host's pending answer.
52
+ *
53
+ * The first request carries a short wait. A pending answer is retried with a
54
+ * capped exponential backoff for about 15 s; any other failure stops at once.
55
+ * Aborting resolves `aborted`, and the sleep is cut short so no timer outlives
56
+ * the pane.
57
+ * @param options - the request, its lifetime and the test seams.
58
+ * @returns the resolved target, the exhausted pending wait, the real failure or
59
+ * the abort.
60
+ */
61
+ export async function waitForWorkspaceTarget(options) {
62
+ const { fetchTarget, signal } = options;
63
+ const sleep = options.sleep ?? abortableSleep;
64
+ const now = options.now ?? Date.now;
65
+ const startedAt = now();
66
+ for (let attempt = 0;; attempt++) {
67
+ if (signal.aborted)
68
+ return { status: "aborted" };
69
+ try {
70
+ return { status: "ready", target: await fetchTarget(signal) };
71
+ }
72
+ catch (error) {
73
+ if (signal.aborted)
74
+ return { status: "aborted" };
75
+ if (!isWorkspacePendingError(error)) {
76
+ return { status: "failed", error };
77
+ }
78
+ }
79
+ const delay = workspaceRetryDelay(attempt, now() - startedAt);
80
+ if (delay === undefined)
81
+ return { status: "pending" };
82
+ await sleep(delay, signal);
83
+ if (signal.aborted)
84
+ return { status: "aborted" };
85
+ }
86
+ }
@@ -0,0 +1,153 @@
1
+ export declare const TEMPLATE_VERSION = 1;
2
+ export declare const TEMPLATE_KIND = "dsh-podman/container-template";
3
+ export declare const TEMPLATE_DIRECTORY = ".dsh-podman";
4
+ export declare const TEMPLATE_EXTENSION = ".yml";
5
+ export declare const BASE_IMAGES: readonly ["archlinux", "ubuntu", "alpine"];
6
+ export type BaseImageName = (typeof BASE_IMAGES)[number];
7
+ export declare const BASE_IMAGE_PACKAGES: Record<BaseImageName, readonly string[]>;
8
+ export declare function isBaseImage(value: unknown): value is BaseImageName;
9
+ export type TemplateMount = {
10
+ kind: "project";
11
+ project: string;
12
+ mode: MountMode;
13
+ } | {
14
+ kind: "volume";
15
+ volume: string;
16
+ destination: string;
17
+ mode: MountMode;
18
+ } | {
19
+ kind: "secret";
20
+ secret: string;
21
+ destination: string;
22
+ } | {
23
+ kind: "tmpfs";
24
+ destination: string;
25
+ };
26
+ export type MountMode = "read_only" | "read_write";
27
+ export interface TemplatePort {
28
+ container: number;
29
+ host?: number;
30
+ protocol: "tcp";
31
+ }
32
+ export interface TemplateImage {
33
+ base: BaseImageName;
34
+ packages: string[];
35
+ }
36
+ export interface ContainerTemplateSpec {
37
+ image?: BaseImageName;
38
+ imageTemplate?: TemplateImage;
39
+ env: Record<string, string>;
40
+ secretEnv: Record<string, string>;
41
+ mounts: TemplateMount[];
42
+ paths: string[];
43
+ ports: TemplatePort[];
44
+ }
45
+ export interface ContainerTemplate {
46
+ version: typeof TEMPLATE_VERSION;
47
+ kind: typeof TEMPLATE_KIND;
48
+ spec: ContainerTemplateSpec;
49
+ }
50
+ export declare class TemplateError extends Error {
51
+ readonly path: string;
52
+ constructor(message: string, path?: string);
53
+ }
54
+ export type EffectiveImage = {
55
+ kind: "base";
56
+ base: BaseImageName;
57
+ } | {
58
+ kind: "template";
59
+ base: BaseImageName;
60
+ packages: string[];
61
+ };
62
+ export interface TemplateImagePlan {
63
+ effective: EffectiveImage;
64
+ imageId: string;
65
+ builtAt: string;
66
+ present: boolean;
67
+ rebuild: boolean;
68
+ needsBuild: boolean;
69
+ reason: "ready" | "missing" | "packages" | "parent";
70
+ }
71
+ export type TemplateWarning = {
72
+ kind: "project_missing";
73
+ project: string;
74
+ path: string;
75
+ } | {
76
+ kind: "secret_missing";
77
+ secret: string;
78
+ } | {
79
+ kind: "secret_env_missing";
80
+ env: string;
81
+ secret: string;
82
+ } | {
83
+ kind: "volume_missing";
84
+ volume: string;
85
+ };
86
+ export declare function canonicalPackages(base: BaseImageName, packages: readonly unknown[]): string[];
87
+ export declare function cleanAbsolutePath(value: unknown): string | undefined;
88
+ export declare function normalizeProjectPath(value: unknown): string | undefined;
89
+ export declare function parseContainerTemplate(text: string): ContainerTemplate;
90
+ export declare function validateTemplate(raw: unknown): ContainerTemplate;
91
+ export declare function effectiveImage(template: ContainerTemplate): EffectiveImage;
92
+ export declare function templateExportImage(imageId: string, images: readonly {
93
+ imageId: string;
94
+ parent: string;
95
+ packages: readonly string[];
96
+ isBase?: boolean;
97
+ }[]): EffectiveImage;
98
+ export declare function templateImagePlan(effective: EffectiveImage, imageId: string, images: readonly {
99
+ imageId: string;
100
+ parent: string;
101
+ packages: readonly string[];
102
+ status?: string;
103
+ builtAt?: string;
104
+ }[]): TemplateImagePlan;
105
+ export declare function sanitizedTemplateName(name: string): string;
106
+ export declare function templateImageId(name: string, absolutePath: string): Promise<string>;
107
+ export declare function templateImageIdFromDigest(name: string, digestHex: string): string;
108
+ export declare function sha256Hex(value: string): Promise<string>;
109
+ export declare function templateRequirements(template: ContainerTemplate, options?: {
110
+ projectExists?: (project: string) => boolean;
111
+ secrets?: readonly string[];
112
+ volumes?: readonly string[];
113
+ }): TemplateWarning[];
114
+ export declare function exportContainerTemplate(container: {
115
+ containerName: string;
116
+ imageId: string;
117
+ env?: Record<string, string>;
118
+ secretEnv?: Record<string, string>;
119
+ mounts?: readonly {
120
+ kind: string;
121
+ projectName?: string;
122
+ destination?: string;
123
+ mode?: string;
124
+ volume?: string;
125
+ secret?: string;
126
+ }[];
127
+ paths?: readonly string[];
128
+ publishedPorts?: readonly {
129
+ port: number;
130
+ hostPort?: number;
131
+ protocol?: string;
132
+ }[];
133
+ }, images: readonly {
134
+ imageId: string;
135
+ parent: string;
136
+ packages: readonly string[];
137
+ isBase?: boolean;
138
+ }[], mainProject?: string): {
139
+ filename: string;
140
+ yaml: string;
141
+ template: ContainerTemplate;
142
+ };
143
+ export declare function renderContainerTemplate(template: ContainerTemplate, mainProject?: string): string;
144
+ export interface TemplateMountInput {
145
+ kind: string;
146
+ project: string;
147
+ destination: string;
148
+ mode: string;
149
+ volume: string;
150
+ secret: string;
151
+ }
152
+ export declare function templateMountInputs(template: ContainerTemplate, workspaceProject?: string): TemplateMountInput[];
153
+ export declare function withForcedProjectMount(mounts: readonly TemplateMountInput[], workspaceProject: string): TemplateMountInput[];