dsh-plugin-container 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin-container contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# DSH 容器
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 左栏容器面板：管理 macOS 上的 Docker（colima / Docker Desktop / OrbStack / remote context）和 Apple `container`。
+
+![概览](docs/docker-overview.png)
+
+## 功能
+
+- Docker / Apple container 双 provider，运行时状态、上下文切换
+- 容器、镜像、卷、网络、Compose、命令
+- 容器启动/停止/重启/删除，镜像 pull/inspect/delete
+- 查看日志、inspect、实时 follow
+- **Attach**：Docker `docker attach`；Apple `container exec`
+- **Exec**：进入容器内部 shell（`docker exec -it <id> /bin/sh`）
+- 镜像架构列（arm64/amd64）
+- 只读 AI 工具：`container_status`、`container_list`、`container_inspect`、`container_logs`
+- AI 诊断会新建独立会话，不污染当前对话
+
+## 要求
+
+- macOS
+- DSH 0.2.x
+- Docker CLI；或安装 [Apple container](https://github.com/apple/container)
+- 网络代理按本机环境配置
+
+## 安装
+
+```bash
+dsh plugin --profile desktop add dsh-plugin-container
+```
+
+重启 DSH。安装器会自动写入 `dsh.profile.bundles`，**不需要手改 `cordis.patch.yml`**。
+
+本地开发版：
+
+```bash
+node scripts/install-profile.mjs --home "$HOME/.dsh" --profile desktop
+```
+
+源码路径模式与 npm 包模式不要同时启用。
+
+## 使用
+
+1. 左栏打开 **容器**
+2. 顶部切换 Docker / Apple container
+3. 容器行操作：
+   - 启动 / 停止 / 重启 / 删除
+   - 日志 / Follow / Inspect
+   - Attach：接管容器主进程
+   - Exec：在容器内开一个新 shell
+   - 问 AI / 诊断：新建独立 DSH 会话，调用只读容器工具
+4. 镜像 tab 可查看架构，或直接用镜像启动容器
+
+## 安全
+
+- 所有 Docker/Apple 命令以当前用户权限执行
+- 无 shell 拼接；命令拆成 argv 直接 spawn
+- 删除、stop、prune 等危险操作需要确认
+- AI 工具只读，不提供 start/stop/rm/prune tool
+- 日志和 inspect 被标记为不可信数据，不能作为指令执行
+
+## 开发
+
+```bash
+npm install
+npm run build     # src/client -> lib/client.js
+npm test          # 46 tests
+npm pack          # 发布前检查
+```
+
+主要结构：
+
+```text
+index.js                 Host 入口
+cordis.patch.yml         bundle 安装 patch
+src/host/service.js      provider 路由 + Docker
+src/host/apple.js        Apple container
+src/host/attach.js       Attach/Exec PTY
+src/host/tools.js        只读 Agent Tools
+src/client/              页面、tabs、i18n、styles
+```

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: docker-sidebar
+      name: dsh-plugin-container

package/index.js

@@ -0,0 +1,138 @@
+/**
+ * Host entry for the Docker sidebar plugin.
+ *
+ * This file is loaded by the DSH Loader from an absolute path, so it imports
+ * only local modules and Node built-ins. The browser half is served separately
+ * from `lib/client.js` through the package's `dsh.client` declaration.
+ *
+ * The browser calls the same `/docker/...` envelope used by the Connection
+ * generic RPC channel. We mount the route ourselves because Connection's
+ * `rpc.handle` helper registers on the service owner's context, which does not
+ * inject `webServer`; the direct route below reuses `connection.admit()` for
+ * the same Host/Origin fence and browser authentication.
+ */
+import { createDockerService } from './src/host/service.js'
+import { registerContainerTools } from './src/host/tools.js'
+
+export const name = 'docker-sidebar'
+export const inject = ['subprocess', 'connection', 'webServer', 'tools', 'systemPrompt']
+
+const CHANNEL = '/docker'
+const MAX_BODY_BYTES = 1024 * 1024
+
+/** @param {import('node:http').IncomingMessage} req */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.byteLength
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+/** @param {import('node:http').ServerResponse} res @param {number} status @param {unknown} body */
+function send(res, status, body, contentType = 'application/json; charset=utf-8') {
+  if (res.writableEnded) return
+  const text = typeof body === 'string' ? body : JSON.stringify(body)
+  res.writeHead(status, { 'content-type': contentType, 'cache-control': 'no-store' })
+  res.end(text)
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {any} ctx
+ * @param {ReturnType<typeof createDockerService>} service
+ */
+async function handleRequest(req, res, ctx, service) {
+  let admission
+  try {
+    admission = ctx.connection.admit(req)
+  } catch (error) {
+    send(res, 403, `forbidden: ${error instanceof Error ? error.message : String(error)}`, 'text/plain; charset=utf-8')
+    return
+  }
+  if ('rejection' in admission) {
+    send(res, admission.rejection, admission.rejection === 401 ? 'unauthorized' : 'forbidden', 'text/plain; charset=utf-8')
+    return
+  }
+  if (req.method !== 'POST') {
+    send(res, 405, 'method not allowed', 'text/plain; charset=utf-8')
+    return
+  }
+  const url = new URL(req.url ?? CHANNEL, 'http://dsh.internal')
+  const endpoint = url.pathname.startsWith(`${CHANNEL}/`) ? url.pathname.slice(CHANNEL.length + 1) : ''
+  if (endpoint === '' || endpoint.includes('/')) {
+    send(res, 404, 'not found', 'text/plain; charset=utf-8')
+    return
+  }
+
+  let message
+  try {
+    message = JSON.parse(await readBody(req))
+  } catch (error) {
+    send(res, 400, `invalid request body: ${error instanceof Error ? error.message : String(error)}`, 'text/plain; charset=utf-8')
+    return
+  }
+  if (
+    message === null ||
+    typeof message !== 'object' ||
+    message.type !== 'client-request' ||
+    typeof message.rpcId !== 'string' ||
+    typeof message.method !== 'string' ||
+    message.method !== endpoint
+  ) {
+    send(res, 400, 'invalid client-request envelope', 'text/plain; charset=utf-8')
+    return
+  }
+
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  res.on('close', abort)
+  try {
+    const result = await service.handle(message.method, message.payload, controller.signal, admission.peer)
+    send(res, 200, { type: 'server-response', rpcId: message.rpcId, result })
+  } catch (error) {
+    send(res, 500, `handler failure: ${error instanceof Error ? error.message : String(error)}`, 'text/plain; charset=utf-8')
+  } finally {
+    res.off('close', abort)
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, any>} [config]
+ */
+export function apply(ctx, config = {}) {
+  const service = createDockerService({
+    subprocess: ctx.subprocess,
+    logger: ctx.logger,
+    config: config ?? {},
+  })
+  try {
+    registerContainerTools(ctx, service)
+    service.enableTools()
+  } catch (error) {
+    ctx.logger?.warn?.('docker: container tool registration failed', error)
+  }
+  ctx.effect(
+    () => ctx.webServer.register({
+      kind: 'prefix',
+      path: CHANNEL,
+      handler: (req, res) => handleRequest(req, res, ctx, service).catch((error) => {
+        send(res, 500, `handler failure: ${error instanceof Error ? error.message : String(error)}`, 'text/plain; charset=utf-8')
+      }),
+    }),
+    'docker: rpc route',
+  )
+  ctx.effect(() => () => service.dispose(), 'docker: jobs')
+}