@exagone313/dsh-podman 1.7.0 → 1.8.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.
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 +46 -28
  112. package/docs/development.zh.md +60 -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
@@ -43,6 +43,7 @@ make lint # vet + oxlint over the TypeScript sources
43
43
  make lint-ts # oxlint only
44
44
  make test-go # go test with the build tags
45
45
  make test # test-go + pnpm test (JS tests, which run against dist/)
46
+ make govulncheck # fixable findings fail; unfixed advisories are tolerated
46
47
  make fmt # gofmt -s + dprint (TypeScript and Markdown)
47
48
  make fmt-check # verify the formatting without rewriting anything
48
49
  make proto # regenerate the protobuf Go bindings with buf
@@ -53,9 +54,9 @@ make image # image-go + the dsh container image
53
54
  ```
54
55
 
55
56
  `make image` depends on `third-party-licenses.pkg`: the `download-licenses`
56
- target runs the Go collector in `scripts/download-licenses`, which shells out to
57
- `go-licenses save` and gathers the project's MIT license plus every third-party
58
- Go license and Apache `NOTICE` into `third-party-licenses.pkg`. That file is
57
+ target runs the `go-download-licenses` tool pinned by the `tool` directive in
58
+ `go.mod`, which gathers the project's MIT license plus every third-party Go
59
+ license and Apache `NOTICE` into `third-party-licenses.pkg`. That file is
59
60
  gitignored (never committed) and is baked into the orchestrator and guest-agent
60
61
  images at `/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers
61
62
  mount the guest-agent image, it also rides along into every workspace container.
@@ -68,14 +69,14 @@ have run first (the `test` target handles this).
68
69
  The `.proto` sources live in `proto/`; the generated Go bindings in
69
70
  `internal/genproto/` are committed. After changing a `.proto`, regenerate them
70
71
  with `make proto`, which runs `buf generate`; Buf must be installed separately —
71
- pin it with `go install github.com/bufbuild/buf/cmd/buf@v1.73.0`. Commit the
72
+ pin it with `go install github.com/bufbuild/buf/cmd/buf@v1.75.0`. Commit the
72
73
  `.proto` change together with the regenerated Go bindings.
73
74
 
74
75
  The JS side loads the raw `.proto` files at runtime via `@grpc/proto-loader`
75
76
  (copied to `dist/grpc/proto/` at build time); no TypeScript bindings are
76
- generated. `make proto-check`, which CI runs, lints the schema, runs
77
- `buf breaking` against the latest release tag, and fails when the committed
78
- bindings differ from the regenerated ones.
77
+ generated. `make proto-check`, which CI runs, lints the schema, runs `buf
78
+ breaking` against the latest release tag, and fails when the committed bindings
79
+ differ from the regenerated ones.
79
80
 
80
81
  ## Naming
81
82
 
@@ -179,25 +180,27 @@ attach creates the pod and its default container again. Restarting the two
179
180
  services never touches workspace containers, and neither action removes volumes,
180
181
  secrets, or project data.
181
182
 
182
- A container that still runs an agent from an older image makes dsh log
183
- `rejected by server because of excess pings` for its guest socket. The message
184
- is harmless (grpc-js backs off and reconnects) and disappears once the container
185
- is recreated; the same message for `orchestrator.sock` means the orchestrator
183
+ A container that still runs an agent from an older image makes dsh log `rejected
184
+ by server because of excess pings` for its guest socket. The message is harmless
185
+ (grpc-js backs off and reconnects) and disappears once the container is
186
+ recreated; the same message for `orchestrator.sock` means the orchestrator
186
187
  service is still running the previous image.
187
188
 
188
189
  ### Development container toolchain
189
190
 
190
191
  A workspace container's root filesystem is read-only and disposable, so the
191
192
  toolchain a contributor builds with needs a workspace volume. No development
192
- image is distributed: build a custom one — the
193
- [setup prompt](development-prompt.md) builds `dsh-podman-tooling` from the
194
- `archlinux` base with `go`, `nodejs` (Node 26), `npm`, `reuse` and
195
- `python-chardet` — and create a workspace volume for the state an image cannot
196
- keep: the Go and npm caches, `gopath` with the `go install`ed tools, and pnpm,
197
- which `package.json` pins to a version the Arch repositories do not carry
198
- (dprint ships with the project's `pnpm install`).
199
-
200
- The prompt mounts that volume as `dsh-podman-toolchain` at `/opt/toolchain`
193
+ image is distributed: the [setup prompt](development-prompt.md) applies the
194
+ committed [`.dsh-podman/develop.yml`](../.dsh-podman/develop.yml) template,
195
+ whose image extends `archlinux` with `go`, `nodejs` (Node 26), `npm`, `reuse`
196
+ and `python-chardet`, and which mounts `deepseek-harness` read-only — clone that
197
+ repository into the projects root first, or loading fails. The template also
198
+ declares a workspace volume for the state an image cannot keep: the Go and npm
199
+ caches, `gopath` with the `go install`ed tools, and pnpm, which `package.json`
200
+ pins to a version the Arch repositories do not carry (dprint ships with the
201
+ project's `pnpm install`).
202
+
203
+ The template mounts that volume as `dsh-podman-toolchain` at `/opt/toolchain`
201
204
  (read-write) and points the container's caches at it, so commands work without
202
205
  sourcing anything:
203
206
 
@@ -212,9 +215,10 @@ Set the commit identity once on the Podman page (sidebar **Plugins** panel →
212
215
  → **Git identity**, so containers get `GIT_AUTHOR_*`/`GIT_COMMITTER_*` without a
213
216
  `~/.gitconfig`.
214
217
 
215
- The prompt applies all of this from inside dsh and can be pasted again to repair
216
- a workspace. Podman stores managed volumes with `DSH_PODMAN_VOLUME_PREFIX`
217
- prepended, so it lists the volume as `dsh-podman-dsh-podman-toolchain`.
218
+ The prompt applies the template from inside dsh and can be pasted again to
219
+ repair a workspace. Podman stores managed volumes with
220
+ `DSH_PODMAN_VOLUME_PREFIX` prepended, so it lists the volume as
221
+ `dsh-podman-dsh-podman-toolchain`.
218
222
 
219
223
  ### Install a local plugin build
220
224
 
@@ -288,21 +292,35 @@ pre-releases like `1.0.0-rc.1` also work). The release workflow
288
292
  the version tag only.
289
293
  3. Publishes the plugin to **npm** (`@exagone313/dsh-podman`) with provenance;
290
294
  pre-releases are published under the `next` dist-tag.
291
- 4. Creates a **GitHub release** with auto-generated notes and attaches the
292
- binaries and the npm tarball.
295
+ 4. Creates a **GitHub release**. Its title is the version; an annotated tag
296
+ supplies its description from the tag message, while a lightweight tag falls
297
+ back to auto-generated notes. No files are attached: the binaries ship in the
298
+ images, and the plugin on npm.
293
299
 
294
300
  The tag must match `package.json`'s version — the workflow fails otherwise — so
295
- bump both with the version script:
301
+ prepare the release with the `release-notes` skill and bump with the version
302
+ script. The skill (`.agents/skills/release-notes/SKILL.md`) drafts the notes
303
+ from the commits since the previous tag — new features, behaviour changes,
304
+ user-visible fixes, and dependency or version updates — has the maintainer
305
+ approve them, and then the approved Markdown is passed to the bump script:
296
306
 
297
307
  ```sh
298
- pnpm bump-version x.y.z # add --dry-run to validate only
308
+ # after the release-notes skill produced an approved list:
309
+ pnpm bump-version x.y.z --notes "<approved notes>" # --notes - reads stdin
299
310
  git push origin master x.y.z
300
311
  ```
301
312
 
313
+ The tag message becomes the GitHub release description. Omitting `--notes` keeps
314
+ the previous behaviour — a single-line `chore: bump version to X` commit and a
315
+ lightweight tag — so the release falls back to auto-generated notes. Add
316
+ `--dry-run` to validate the version and notes without changing anything.
317
+
302
318
  `scripts/bump-version.mjs` checks that the version is a semver release or
303
319
  pre-release that increases the current one, writes it to `package.json`, commits
304
320
  `chore: bump version to X`, and creates the tag; it pushes nothing, and it
305
- requires the `master` branch with a clean working tree. The tag is also what the
321
+ requires the `master` branch with a clean working tree. With `--notes`, the
322
+ commit body and the annotated tag message carry the approved notes; `--notes -`
323
+ reads them from stdin, and an empty body is rejected. The tag is also what the
306
324
  built plugin and binaries report, since `scripts/generate-version.mjs` derives
307
325
  the embedded version from `git describe --tags`. Pre-releases (`1.0.0-rc.1`) are
308
326
  bumped the same way.
@@ -26,7 +26,7 @@ SPDX-License-Identifier: MIT
26
26
 
27
27
  ```sh
28
28
  pnpm install
29
- pnpm run build # tsc host + tsc client -> dist/, copies proto/ -> dist/grpc/proto/
29
+ pnpm run build # tsc 主进程 + tsc 客户端 -> dist/,并复制 proto/ -> dist/grpc/proto/
30
30
  ```
31
31
 
32
32
  Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动,它们需要宿主机的 C
@@ -35,25 +35,26 @@ Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动,它们需要宿
35
35
  `Makefile` 封装了常见的工作流:
36
36
 
37
37
  ```sh
38
- make build-go # build the Go binaries into bin/<os>-<arch>/
38
+ make build-go # 构建 Go 二进制到 bin/<os>-<arch>/
39
39
  make build # build-go + pnpm-build
40
- make vet # gofmt -s check + go vet with the build tags
41
- make lint # vet + oxlint over the TypeScript sources
42
- make lint-ts # oxlint only
43
- make test-go # go test with the build tags
44
- make test # test-go + pnpm test (JS tests, which run against dist/)
45
- make fmt # gofmt -s + dprint (TypeScript and Markdown)
46
- make fmt-check # verify the formatting without rewriting anything
47
- make proto # regenerate the protobuf Go bindings with buf
48
- make proto-check # buf lint + buf breaking + check the committed bindings are current
49
- make download-licenses # generate third-party-licenses.pkg from the project and third-party Go licenses
50
- make image-go # build the Go container images (orchestrator, guest-agent, gateway)
51
- make image # image-go + the dsh container image
40
+ make vet # gofmt -s 检查 + 使用构建标签的 go vet
41
+ make lint # vet + 对 TypeScript 源码运行 oxlint
42
+ make lint-ts # 仅运行 oxlint
43
+ make test-go # 使用构建标签运行 go test
44
+ make test # test-go + pnpm test(针对 dist/ 运行的 JS 测试)
45
+ make govulncheck # 可修复的发现导致失败;未修复的公告会被容忍
46
+ make fmt # gofmt -s + dprint(TypeScript 与 Markdown)
47
+ make fmt-check # 校验格式但不改写任何文件
48
+ make proto # 使用 buf 重新生成 protobuf Go 绑定
49
+ make proto-check # buf lint + buf breaking + 检查已提交绑定是否最新
50
+ make download-licenses # 从项目与第三方 Go 许可证生成 third-party-licenses.pkg
51
+ make image-go # 构建 Go 容器镜像(orchestrator、guest-agent、gateway)
52
+ make image # image-go + dsh 容器镜像
52
53
  ```
53
54
 
54
- `make image` 依赖 `third-party-licenses.pkg`:`download-licenses` 目标会运行
55
- `scripts/download-licenses` 中的 Go 收集器,它调用 `go-licenses save` 并将项目的
56
- MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到
55
+ `make image` 依赖 `third-party-licenses.pkg`:`download-licenses` 目标会运行由
56
+ `go.mod` 的 `tool` 指令固定的 `go-download-licenses` 工具,它会将项目的 MIT
57
+ 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到
57
58
  `third-party-licenses.pkg` 中。该文件被 gitignore (从不提交),并被烘焙进
58
59
  orchestrator 和 guest-agent 镜像,位于
59
60
  `/usr/share/licenses/dsh-podman/LICENSE`;由于工作区容器会挂载 guest-agent
@@ -65,15 +66,15 @@ orchestrator 和 guest-agent 镜像,位于
65
66
  ## Protobuf
66
67
 
67
68
  `.proto` 源文件位于 `proto/`;生成的 Go 绑定位于
68
- `internal/genproto/`,会被提交。修改 `.proto` 后,请用 `make proto`(即运行
69
- `buf generate`)重新生成。Buf 需单独安装——请用
70
- `go install github.com/bufbuild/buf/cmd/buf@v1.73.0` 固定版本。请将 `.proto`
69
+ `internal/genproto/`,会被提交。修改 `.proto` 后,请用 `make proto`(即运行 `buf
70
+ generate`)重新生成。Buf 需单独安装——请用 `go install
71
+ github.com/bufbuild/buf/cmd/buf@v1.75.0` 固定版本。请将 `.proto`
71
72
  改动与重新生成的 Go 绑定一起提交。
72
73
 
73
74
  JS 端在运行时通过 `@grpc/proto-loader` 加载原始 `.proto` 文件(构建时复制到
74
75
  `dist/grpc/proto/`);不生成 TypeScript 绑定。CI 运行的 `make proto-check`
75
- 会校验 schema、针对最新发布标签运行
76
- `buf breaking`,若已提交的绑定与重新生成的结果不一致则失败。
76
+ 会校验 schema、针对最新发布标签运行 `buf
77
+ breaking`,若已提交的绑定与重新生成的结果不一致则失败。
77
78
 
78
79
  ## 命名
79
80
 
@@ -91,8 +92,8 @@ camelCase;持久化的 TOML 状态使用下划线标签。
91
92
  ### 构建
92
93
 
93
94
  ```bash
94
- make # builds plugin and go binaries
95
- make image # build images
95
+ make # 构建插件与 Go 二进制
96
+ make image # 构建镜像
96
97
  ```
97
98
 
98
99
  ### 运行本地镜像(Quadlet)
@@ -142,9 +143,9 @@ systemctl --user daemon-reload
142
143
  ### 部署改动
143
144
 
144
145
  ```bash
145
- make # Go binaries + the plugin bundle
146
- make image # orchestrator, guest-agent, gateway and dsh images
147
- npm pack # the plugin archive the dsh entrypoint installs
146
+ make # Go 二进制 + 插件归档
147
+ make image # orchestrator、guest-agent、gateway 与 dsh 镜像
148
+ npm pack # dsh 入口要安装的插件归档
148
149
  systemctl --user restart dsh dsh-podman-orchestrator dsh-podman-gateway
149
150
  ```
150
151
 
@@ -167,20 +168,22 @@ guest agent 之后,请自行重建容器:
167
168
  及其所有容器都会被移除,下次接入时会重新创建 pod
168
169
  与默认容器。重启这两个服务绝不会触及工作区容器,上述两种操作也都不会删除卷、机密或项目数据。
169
170
 
170
- 仍在运行旧镜像中 guest agent 的容器会让 dsh 为其 guest 套接字记录
171
- `rejected by server because of excess pings`。该消息无害(grpc-js
171
+ 仍在运行旧镜像中 guest agent 的容器会让 dsh 为其 guest 套接字记录 `rejected by
172
+ server because of excess pings`。该消息无害(grpc-js
172
173
  会退避并重连),重建该容器后即消失;若同样的消息出现在 `orchestrator.sock`
173
174
  上,则说明 orchestrator 服务仍在运行上一个镜像。
174
175
 
175
176
  ### 开发容器工具链
176
177
 
177
- 工作区容器的根文件系统是只读且一次性的,因此贡献者构建所用的工具链需要工作区的一个卷。项目并不分发开发镜像:请自行构建一个自定义镜像——[设置提示词](development-prompt.zh.md)
178
- 会以 `archlinux` 为父镜像构建 `dsh-podman-tooling`,包含 `go`、`nodejs`(Node
179
- 26)、`npm`、`reuse` 和 `python-chardet`——并为镜像无法保存的状态创建工作区卷:Go
180
- 与 npm 缓存、含 `go install` 工具的 `gopath`, 以及 `package.json`
181
- 固定版本、Arch 仓库没有的 pnpm(dprint 随项目的 `pnpm install` 一并安装)。
178
+ 工作区容器的根文件系统是只读且一次性的,因此贡献者构建所用的工具链需要工作区的一个卷。项目并不分发开发镜像:[设置提示词](development-prompt.zh.md)会应用已提交的
179
+ [`.dsh-podman/develop.yml`](../.dsh-podman/develop.yml) 模板,其镜像以
180
+ `archlinux` 为基础并加入 `go`、`nodejs`(Node 26)、`npm`、`reuse` 和
181
+ `python-chardet`,同时以只读方式挂载 `deepseek-harness`——请先把该仓库克隆到
182
+ projects 根目录,否则无法加载。模板还为镜像无法保存的状态声明工作区卷:Go 与 npm
183
+ 缓存、含 `go install` 工具的 `gopath`,以及 `package.json` 固定版本、Arch
184
+ 仓库没有的 pnpm(dprint 随项目的 `pnpm install` 一并安装)。
182
185
 
183
- 提示词会把该卷以 `dsh-podman-toolchain` 挂载到
186
+ 模板会把该卷以 `dsh-podman-toolchain` 挂载到
184
187
  `/opt/toolchain`(读写),并让容器的缓存都指向它,因此无需 source
185
188
  任何脚本即可使用:
186
189
 
@@ -194,7 +197,7 @@ guest agent 之后,请自行重建容器:
194
197
  身份** 中设置一次提交身份,容器便无需 `~/.gitconfig` 即可获得
195
198
  `GIT_AUTHOR_*`/`GIT_COMMITTER_*`。
196
199
 
197
- 提示词会在 dsh 内完成上述全部配置,并且可以反复粘贴以修复工作区。Podman
200
+ 提示词会在 dsh 内应用该模板,并且可以反复粘贴以修复工作区。Podman
198
201
  存储受管卷时会加上 `DSH_PODMAN_VOLUME_PREFIX` 前缀,因此该卷显示为
199
202
  `dsh-podman-dsh-podman-toolchain`。
200
203
 
@@ -242,8 +245,8 @@ zizmor)、`ci-code.yml`(Go、JS、镜像、Trivy)、`ci-docs.yml`(dprint
242
245
  - **reuse** — REUSE 许可证合规检查。
243
246
  - **go** — 构建、`gofmt -s` 检查、vet、测试和 govulncheck(Go 漏洞)。未修复的
244
247
  发现不会导致任务失败;可修复的会导致失败。
245
- - **js** — 安装、TypeScript 格式检查、lint、类型检查、构建、测试和
246
- `pnpm audit`。
248
+ - **js** — 安装、TypeScript 格式检查、lint、类型检查、构建、测试和 `pnpm
249
+ audit`。
247
250
  - **docs** — Markdown 格式检查(通过 `make fmt-check-md` 运行 `dprint`)。
248
251
  - **images** — 构建 orchestrator 和 guest-agent
249
252
  镜像(仅在测试任务通过后运行);**dsh image** 构建 `Containerfile.dsh`。
@@ -264,21 +267,32 @@ zizmor)、`ci-code.yml`(Go、JS、镜像、Trivy)、`ci-docs.yml`(dprint
264
267
  发布以及任何带连字符的标签都属于预发布:只打版本标签。
265
268
  3. 将插件发布到 **npm**(`@exagone313/dsh-podman`),附带来源证明; 预发布在
266
269
  `next` dist-tag 下发布。
267
- 4. 创建带有自动生成说明的 **GitHub release**,并附上 二进制文件和 npm tarball。
270
+ 4. 创建 **GitHub release**。标题为版本号;附注标签以其标签信息作为说明,轻量标签
271
+ 回退到自动生成的说明。不会附加任何文件:二进制文件随镜像发布,插件发布在 npm
272
+ 上。
268
273
 
269
- 标签必须与 `package.json`
270
- 中的版本一致——否则工作流会失败——因此请用版本脚本同时更新两者:
274
+ 标签必须与 `package.json` 中的版本一致——否则工作流会失败——因此请先用
275
+ `release-notes` skill 准备发布,再用版本脚本更新两者。该 skill
276
+ (`.agents/skills/release-notes/SKILL.md`)会根据上一个标签以来的提交起草说明——新
277
+ 功能、行为变更、用户可见的修复,以及依赖或版本更新——交由维护者批准,随后把批准的
278
+ Markdown 传给版本脚本:
271
279
 
272
280
  ```sh
273
- pnpm bump-version x.y.z # 加上 --dry-run 则仅校验
281
+ # 用 release-notes skill 起草并批准说明后:
282
+ pnpm bump-version x.y.z --notes "<批准的说明>" # --notes - 从标准输入读取
274
283
  git push origin master x.y.z
275
284
  ```
276
285
 
286
+ 标签信息会成为 GitHub release 的说明。省略 `--notes` 会保留原有行为——单行
287
+ `chore: bump version to X` 提交和轻量标签——因此 release
288
+ 会回退到自动生成的说明。加上 `--dry-run` 可只校验版本与说明,不做任何改动。
289
+
277
290
  `scripts/bump-version.mjs` 会检查版本是否为递增的 Semver
278
- 正式版或预发布版,将其写入 `package.json`,提交
279
- `chore: bump version to X`,并创建标签;它不会推送,且要求处于 `master`
280
- 分支且工作区干净。标签同时也是构建出的插件与二进制文件所报告的版本,因为
281
- `scripts/generate-version.mjs` 从 `git describe --tags`
291
+ 正式版或预发布版,将其写入 `package.json`,提交 `chore: bump version to
292
+ X`,并创建标签;它不会推送,且要求处于 `master` 分支且工作区干净。使用 `--notes`
293
+ 时,提交正文和附注标签信息都会带上批准的说明; `--notes -`
294
+ 从标准输入读取,空正文会被拒绝。标签同时也是构建出的插件与二进制文件所
295
+ 报告的版本,因为 `scripts/generate-version.mjs` 从 `git describe --tags`
282
296
  推导嵌入的版本。预发布版(`1.0.0-rc.1`)也用同样的方式递增。
283
297
 
284
298
  也可以在 Actions 页面通过 `workflow_dispatch`
package/docs/uninstall.md CHANGED
@@ -47,9 +47,9 @@ root and only `podman unshare` can remove them, from the user namespace.
47
47
 
48
48
  ### Keep dsh without dsh-podman
49
49
 
50
- Run dsh directly instead of from the image — as the harness documents, with
51
- `npx @deepseek-ai/dsh web` — after removing the plugin from the profile, so dsh
52
- stops loading it and its built-in plugins are active again:
50
+ Run dsh directly instead of from the image — as the harness documents, with `npx
51
+ @deepseek-ai/dsh web` — after removing the plugin from the profile, so dsh stops
52
+ loading it and its built-in plugins are active again:
53
53
 
54
54
  ```bash
55
55
  npx @deepseek-ai/dsh plugin --profile web remove @exagone313/dsh-podman
@@ -44,8 +44,8 @@ namespace)中用 `podman unshare` 删除。
44
44
 
45
45
  ### 保留 dsh 但不使用 dsh-podman
46
46
 
47
- 改为直接运行 dsh,而不是从镜像运行——如 harness 文档所述,使用
48
- `npx @deepseek-ai/dsh web`——在此之前先从 profile 中移除插件,这样 dsh
47
+ 改为直接运行 dsh,而不是从镜像运行——如 harness 文档所述,使用 `npx
48
+ @deepseek-ai/dsh web`——在此之前先从 profile 中移除插件,这样 dsh
49
49
  便不再加载它,其内置插件也会重新启用:
50
50
 
51
51
  ```bash
package/docs/usage.md CHANGED
@@ -68,6 +68,13 @@ dsh-podman organizes the images its containers run into three tiers:
68
68
  image or another custom image — inheriting its package manager and adding
69
69
  extra packages on top. They are referenced by their short name (e.g.
70
70
  `valkey`).
71
+ - **Template images** are custom images a container template builds. Their short
72
+ name is `template-<sanitized file basename>-<first 8 hex of sha256(absolute
73
+ template path)>`, so two same-named templates in different projects never
74
+ share an image. A template whose packages are all part of the base's built-in
75
+ list refers to the **base image** and builds nothing; on export that is
76
+ written as `image: <base>`, even for a custom image whose extra packages all
77
+ turned out to be base packages.
71
78
 
72
79
  Image references (`imageId`, `parent`, `image`) are **short names only** (no
73
80
  registry prefix, no `:tag`).
@@ -122,15 +129,14 @@ on `bash`) is accepted but has no effect here: the sandbox is bypassed inside
122
129
  the container, so the plugin grants the escalation without prompting.
123
130
 
124
131
  The prompt's reason is a full sentence naming the action and the objects it
125
- touches, quoting every identifier — for example
126
- `Add mount to container "web": volume "data" (read-only)`. It covers the
127
- container image, each mount's kind and destination, the environment variable
128
- keys, the secret env var names, and the resolved file path. It follows the UI
129
- language: the browser client records the active locale in the plugin's
130
- `uiLocale` preference, which the Host persists in the plugin config (English
131
- when unset). A policy denial — a read-only sandbox, or a destination on a
132
- project mount — is reported in the same language. The Podman page's actions are
133
- direct control calls and are not gated.
132
+ touches, quoting every identifier — for example `Add mount to container "web":
133
+ volume "data" (read-only)`. It covers the container image, each mount's kind and
134
+ destination, the environment variable keys, the secret env var names, and the
135
+ resolved file path. It follows the UI language: the browser client records the
136
+ active locale in the plugin's `uiLocale` preference, which the Host persists in
137
+ the plugin config (English when unset). A policy denial — a read-only sandbox,
138
+ or a destination on a project mount — is reported in the same language. The
139
+ Podman page's actions are direct control calls and are not gated.
134
140
 
135
141
  `container_start`, `container_recreate`, and `container_bash` accept an `env`
136
142
  map applied to the container (or the bash process); `container_exec` and
@@ -170,6 +176,14 @@ managed `DSH_*` fact.
170
176
  | `image_rebuild` ✱ | `imageId` | Rebuild an existing custom image in place |
171
177
  | `image_remove` ✱ | `imageId` | Remove a built image; refused while a workspace or container still references it |
172
178
 
179
+ ### Container templates
180
+
181
+ | Tool | Params | Description |
182
+ | --------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
183
+ | `container_template_export` | `container` | Export a container as a container-template YAML string (root base image, recursive package union minus the base's built-ins, mounts, environment, secret names, PATH additions and ports with explicit `protocol: tcp`); changes nothing |
184
+ | `container_template_load` ✱ | `template`, optional `container` | Load a project template: build its image when needed, then create a container, publish its ports and report failures as warnings; the workspace project mount is added read-write |
185
+ | `container_template_save` ✱ | `container`, `name` | Save the source `container` as a template: the tool exports it to canonical YAML itself (there is no YAML argument) and writes the result through the default container's guest agent as `name` in the project's `.dsh-podman` directory, adding `.yml` when the basename has no YAML suffix and creating the directory when missing |
186
+
173
187
  ### Containers
174
188
 
175
189
  | Tool | Params | Description |
@@ -422,21 +436,54 @@ a stacked block.
422
436
 
423
437
  A workspace with no container gets a **Create container** button; a workspace
424
438
  that already has containers gets an **Add container** button for additional,
425
- named containers. Every workspace row also offers **Remove containers**, which
426
- removes that workspace's dsh-podman containers and its pod, and the
427
- orchestrator's record for it (volumes, secrets, and project data are kept, and
428
- the dsh workspace itself is untouched); removing a workspace's last container
429
- removes its pod as well, so an empty pod is never left behind.
439
+ named containers. A **Load template** button follows it: a first popup lists the
440
+ project's templates from `.dsh-podman` (read on the dsh host, like the directory
441
+ picker) and offers **Upload from the browser**; choosing one only selects it,
442
+ and **Next** opens a second popup. That popup explains what the template will
443
+ stage — the image (and whether it must be built), the mounts, warnings for
444
+ project mount directories that do not exist, the required named secrets with
445
+ which ones exist, and the ports — with a **New container** / **Edit existing
446
+ container** destination choice at the top. When the image is missing it carries
447
+ an explicit **Build image** button; once the image is ready the same card offers
448
+ **Rebuild image**, which rebuilds it even though it is current. **Continue**
449
+ stays disabled while a build or rebuild runs, after a failure, and until the
450
+ other requirements hold; the blocking reason sits in the footer, left of the
451
+ actions. **Continue** opens the create editor prefilled from the template's
452
+ draft — the workspace's default container editor when it holds no container yet,
453
+ otherwise the named editor where the container name is chosen — or, with **Edit
454
+ existing container** chosen, the chosen container's edit editor, with the
455
+ template's fields filled in, the fields the template omits showing as the
456
+ container currently has them, and the template's ports left out of the draft.
457
+ The image card's action is the only thing that builds here; nothing is created
458
+ or replaced until the editor's own Apply.
459
+
460
+ A create's Apply makes the default container when the workspace held none, or
461
+ the named container chosen in the create editor otherwise, and publishes the
462
+ template's ports after the container exists; a publishing failure is reported as
463
+ a warning rather than failing the create. A replace's Apply updates the
464
+ container through the normal edit-apply path — nothing is removed or recreated
465
+ up front — and the template's ports are published afterwards, their failures
466
+ again reported as warnings. The workspace project mount is added silently,
467
+ read-write and forced; nothing is saved until that editor's own Apply. Every
468
+ workspace row also offers **Remove containers**, which removes that workspace's
469
+ dsh-podman containers and its pod, and the orchestrator's record for it
470
+ (volumes, secrets, and project data are kept, and the dsh workspace itself is
471
+ untouched); removing a workspace's last container removes its pod as well, so an
472
+ empty pod is never left behind.
430
473
 
431
474
  #### Containers
432
475
 
433
476
  The block's identity line carries the container name, its state chip and its
434
477
  created time (relative, with the exact instant as a tooltip).
435
478
 
436
- Its **Edit**, **Recreate** and **Remove** actions sit at the right end of that
437
- line, right-aligned while the block has room and below the name once it does
438
- not: **Recreate** rebuilds the container as it is once the confirmation naming
439
- it is accepted.
479
+ Its **Edit**, **Recreate**, **Export template** and **Remove** actions sit at
480
+ the right end of that line, right-aligned while the block has room and below the
481
+ name once it does not: **Recreate** rebuilds the container as it is once the
482
+ confirmation naming it is accepted. **Export template** writes the container as
483
+ a container-template YAML and opens the browser's save dialog; a custom image's
484
+ parent chain is folded into its root base plus the recursive package union minus
485
+ that base's built-ins, so an image whose extra packages were all base packages
486
+ exports as `image: <base>`.
440
487
 
441
488
  One container is reserved: `ptc`, the container that serves workflows and PTC
442
489
  runs. It belongs to no workspace, so it never appears inside one: its card sits
@@ -506,6 +553,13 @@ which the destination path is derived: the project's path mirrored under the
506
553
  projects root, previewed in a read-only field, since a project mount never takes
507
554
  a destination of its own.
508
555
 
556
+ A project path typed in the Add-mount dialog rather than picked with **Browse…**
557
+ is checked against the projects root on the dsh host when the mount is added: an
558
+ inline error refuses an absolute path, one that climbs out of the root with
559
+ `..`, and one that names no existing directory. In the list a project mount's
560
+ path is fixed, shown with the read-only lock, so it is chosen when the mount is
561
+ added.
562
+
509
563
  When a container is being created or added, each project or volume mount's mode
510
564
  is a dropdown (read-only/read-write), so the workspace project mount can be
511
565
  created read-only in one step, while secret and tmpfs mounts carry no mode
@@ -527,8 +581,10 @@ edited one becomes that container's own.
527
581
  Secret environment variables are attached by adding a row and picking a named
528
582
  secret, with the variable name editable in place like an environment variable's
529
583
  key, switched to another secret in place, or removed from that row's own
530
- **Remove**. A workspace without secrets offers **Create secret** in place of the
531
- secret picker, opening the secret form on top of the dialog.
584
+ **Remove** — which is how a requirement a template brought in is dropped. A row
585
+ whose secret no longer exists offers **Create secret** in place, opening the
586
+ form on the name that row requires; a workspace without secrets offers **Create
587
+ secret** too. A newly created secret is selected in the row that asked for it.
532
588
 
533
589
  A variable name is required and must be unique across the environment variables
534
590
  and the secret environment variables.
@@ -628,6 +684,81 @@ Directly below that table sits the shared PTC container's card: its identity,
628
684
  its state and **PTC** chips, its relative creation time, its read-only image and
629
685
  its **Recreate**/**Remove** actions.
630
686
 
687
+ ### Container templates
688
+
689
+ A container template is a YAML file in a project's `.dsh-podman` directory:
690
+
691
+ ```yaml
692
+ version: 1
693
+ kind: dsh-podman/container-template
694
+ spec:
695
+ imageTemplate: # or image: ubuntu (exactly one of the two)
696
+ base: ubuntu # archlinux | ubuntu | alpine only
697
+ packages:
698
+ - git
699
+ - ripgrep
700
+ env:
701
+ NODE_ENV: development
702
+ secretEnv:
703
+ GITHUB_TOKEN: github-token # variable -> secret name, never a value
704
+ mounts:
705
+ - kind: project # no destination; mode defaults to read_only
706
+ project: app
707
+ mode: read_write
708
+ - kind: volume
709
+ volume: cache
710
+ destination: /cache
711
+ mode: read_write
712
+ - kind: secret # read-only, no mode
713
+ secret: npm-token
714
+ destination: /root/.npmrc
715
+ - kind: tmpfs # destination only
716
+ destination: /tmp/scratch
717
+ paths:
718
+ - /usr/local/bin
719
+ ports:
720
+ - container: 8080
721
+ host: 8080
722
+ protocol: tcp # protocol required, tcp only
723
+ - container: 3000
724
+ protocol: tcp # host optional
725
+ ```
726
+
727
+ That is the canonical rendering: block style throughout with two-space
728
+ indentation, and an empty `env`, `secretEnv`, `mounts`, `paths` or `ports` group
729
+ omitted rather than written as `{}` or `[]` (the parser supplies the empty
730
+ defaults). Project and volume mounts carry an optional `mode` (`read_only` or
731
+ `read_write`); omitting it means `read_only`, the editor's default. Secret
732
+ mounts are fixed read-only and tmpfs mounts carry no mode at all. Mounts are
733
+ grouped in the container card's order — project, volume, secret, tmpfs — and
734
+ keep their order within a kind. The four Git identity variables
735
+ (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
736
+ `GIT_COMMITTER_EMAIL`) are never written to a template, and a template that
737
+ declares them is loaded without them: they come from the default environment.
738
+
739
+ The format is strict: an unknown `version` or `kind`, any key outside the sets
740
+ above (no `command`, `resources`, tmpfs `size`, or port `protocol` other than
741
+ `tcp`), both or neither of `image`/`imageTemplate`, a base name outside the
742
+ three declared bases, a mount key that does not match its kind (a project mount
743
+ with a destination, a secret or tmpfs mount with a mode, a tmpfs with a source
744
+ or `size`), and a secret value instead of a secret name are refused rather than
745
+ ignored. Secret values are never stored in a template, only the names of the
746
+ secrets a container should receive.
747
+
748
+ The package list is canonical on both sides: packages already in the base's
749
+ built-in list are dropped, what remains is deduplicated and sorted, and an empty
750
+ remainder means the base image. The template image is rebuilt when its package
751
+ list (or its parent base) differs from what the image list reports, and a
752
+ superseded template image is deleted once no container references it.
753
+
754
+ `container_template_save` goes through the guest agent (the dsh host only reads
755
+ the project): it takes the source `container` and a plain `name` basename — not
756
+ a YAML document — exports that container itself, and writes the canonical YAML
757
+ as `name` (with `.yml` added when the name has no YAML suffix), creating
758
+ `.dsh-podman` when missing. It refuses a name that is not a plain basename and
759
+ reports a read-only project mount as a clean permission error rather than an I/O
760
+ failure.
761
+
631
762
  ## Podman terminal
632
763
 
633
764
  The plugin owns a **Podman terminal** right-Sidebar tab. It replaces the
@@ -700,14 +831,15 @@ are global and all remain available, split as:
700
831
  - **Direct:** `image_list`, `image_get`, `container_list`, `container_read`,
701
832
  `container_glob`, `container_grep`, `container_mount_list`, `volume_list`,
702
833
  `secret_list`, `secret_create`, `daemon_list`, `daemon_logs`, `daemon_stop`,
703
- `daemon_restart`, `container_start` (asks only when `mounts` or `secretEnv` is
704
- passed).
834
+ `daemon_restart`, `container_template_export`, `container_start` (asks only
835
+ when `mounts` or `secretEnv` is passed).
705
836
  - **Approval-gated** (the usual `✱` tools): `image_build`, `image_rebuild`,
706
837
  `image_rebuild_all`, `image_remove`, `container_recreate`, `container_remove`,
707
838
  `container_mount_add`, `container_mount_remove`, `container_mount_update`,
708
839
  `container_path_set`, `container_path_add`, `container_path_remove`,
709
840
  `volume_remove`, `secret_remove`, `container_secret_add`,
710
- `container_secret_remove`.
841
+ `container_secret_remove`, `container_template_load`,
842
+ `container_template_save`.
711
843
  - **Approval-gated only in this preset:** `container_bash`, `container_exec`,
712
844
  `container_write`, `container_edit`, `daemon_start` — so the agent can run
713
845
  commands, edit container files, or start daemons once the user approves,