dsh-asuta-worktree-control 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 更新日志
+
+## 未发布
+
+- 侧边对话转为独立会话时登记原工作树成员，保留项目分组和实际目录；提供可选共享服务，兼容旧侧边会话的归属修复。
+- 修复保存环境期间修改操作行导致校验错误丢失：保存时暂时锁定表单，无法定位输入项的错误显示在面板顶部。
+- 保存环境时自动忽略完全空白的操作；未填完整或超长的操作按原始序号提示，并定位对应输入框，校验失败保留表单和原配置。
+- 修复 Git 操作期间环境命令绕过会话互斥的问题；等待操作完成后重新检查目录和环境，只在登记终端任务时短暂持锁。
+- 修复内置终端单独按 Esc 一直等待下一次输入的问题；短暂等待分片按键序列后自动发送，并在停止或退出时清理定时器。
+- 环境命令按钮与 Git Diff 的“变更”按钮同组显示，固定在其右侧；未启用 Git Diff 时保留标题栏入口。
+- 修复历史对话冷启动时环境命令按钮因会话尚未连接而永久隐藏；等待会话打开后检查，检查失败时提供错误提示和重试入口。
+- 在“变更”旁增加当前环境的快捷命令菜单，支持切换环境和直接打开环境管理页。
+- 手动操作和工作树自动初始化统一接入内置侧栏终端，实时显示命令与输出、保留结果，支持 Ctrl+C、停止按钮和关闭终端后停止任务。
+- 运行中重复点击只定位已有任务；新一次执行使用独立终端。保留沙箱及失败中止语义，并保护正在执行命令的工作树不被本插件切换或清理。
+- 手动操作使用多行命令框，支持 Enter 换行、粘贴与保存多行脚本；名称与移除按钮单独排列。
+- 环境命令默认失败即停止，Windows PowerShell 同时检查外部程序退出码，避免 Git 拉取失败后继续执行重置和清理。
+- 修复 PowerShell 成功命令的 stderr 重定向被误判、catch 中退出码被清零，以及合法 data 块被改写导致解析失败的问题。
+- 修复 DSH 0.2.2 普通对话分支不再包含 `parentSession` 后，无法在新工作树中创建分支的问题；改为校验所选位置的继承历史，并分别提示来源不匹配和源对话忙碌。
+
+## 0.1.0
+
+- 新增 DSH 对话内 Git 工作树创建、切换、差异操作、快照归档与恢复。
+- 新增仓库级保留数量设置、固定保护、.worktreeinclude 与可选 setup 脚本。
+- 新增本地与工作树间的成果交接、原工作树返回、新分支创建与项目 actions。
+- 支持自定义工作树根目录；归档对话时快照不再被使用的关联工作树。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Plugin Lab 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,62 @@
-# Temporary Holding Version
+# 工作树管理
 
-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 对话提供独立的 Git 工作树管理面板。创建或切换工作树时，只更新当前会话的工作目录，因此对话历史保持连续。
+
+## 功能
+
+- 从当前提交或本地/远端分支创建 detached 工作树，也可以同时新建分支。
+- 助手回复下方的原生分支按钮会打开两个选项：在当前工作区沿用原生方式创建对话分支，或立即创建新工作树并打开分支对话。新工作树默认复制源目录的未提交改动；当前目录不是可用 Git 工作树、源对话运行中或只读时会说明原因。
+- 新对话通过设置弹层选择是否创建工作树、基础分支和本地环境；工作树在首条消息发送时创建，详细设置继续使用右侧面板。
+- 侧边栏为所有 Git 附加工作树中的对话显示分叉标记，依据对话当前目录更新。
+- 配合侧边对话插件，转为独立会话后继续归属原项目并共用原工作树，登记为另一条工作树会话。两个会话共享文件，归档其中一个不会清理仍被另一个使用的工作树。
+- 选择把当前工作树的暂存、未暂存和未跟踪改动复制到新树；源工作树不被修改。
+- 按 .worktreeinclude 的 .gitignore 风格模式复制忽略文件，并自动带入被忽略的 AGENTS.override.md；不覆盖目标已有文件，拒绝符号链接和越界路径。
+- 每个项目可保存、编辑、删除多份本地环境配置，设置默认环境或为单个对话切换；可将 .codex/environments/environment.toml 导入为可编辑副本。
+- 环境配置可包含新工作树创建后的 setup 脚本和手动执行的项目操作。初始化失败时仍会进入新工作树并发送首条消息，详细页会显示失败原因；切换已有对话的环境不会自动重跑脚本。
+- 在同一对话中切换本地目录或其他 Git 工作树，也可把成果交接到本地或该对话之前使用的工作树。
+- 查看差异，按文件暂存、取消暂存或丢弃；提交已暂存内容、推送分支，并通过 GitHub CLI 打开 PR 创建流程。
+- 归档前创建可恢复快照；恢复时把快照内容还原为暂存改动。
+- 归档已加载的对话时，自动快照并清理不再被其他未归档对话使用的关联工作树；固定的工作树保留。未加载对话关联的旧树由保留数量策略后续清理。
+- 每个仓库可设置自动保留数量（默认 15，0 表示关闭）。自动归档会跳过固定、当前或活动对话正在使用的工作树。
+
+## 环境命令
+
+对话右上角“变更”旁的运行菜单列出当前环境的手动命令，可从“切换环境”更换此对话的环境，或从“管理环境”进入配置页。无 Git 工作目录时不显示此入口。切换环境不会自动重新初始化。
+
+快捷菜单、详细页的手动操作及新工作树的自动初始化都会打开 DSH 内置侧栏终端，在对应工作树目录实时显示命令、输出和执行结果。同一命令运行中再次点击会定位到原终端，不会重复启动；结束后保留日志，新一次执行使用新的终端，可关闭已完成的终端释放名额。支持终端 Ctrl+C 和菜单中的“停止”；关闭执行终端也会停止对应命令。手动操作可用于持续运行的开发服务，初始化脚本最多运行 10 分钟。
+
+需要启用 DSH 内置终端，并在本机 PATH 中提供 Node.js。实际脚本继续遵守对话的权限限制；初始化会等待终端连接后才开始，45 秒内无法打开时明确报错并保留已创建的工作树。执行期间不能通过本插件修改同一工作树的 Git 状态或切换、清理工作树。
+
+“手动操作”的名称与命令分开编辑，命令框支持 Enter 换行、粘贴多行脚本并保留换行。多条命令共享同一脚本作用域，在当前工作树目录执行。
+保存时自动忽略名称和命令都为空（含纯空白字符）的操作；只填一项时会标明操作序号、提示缺少的字段并聚焦输入框。保存失败保留已填写内容和原配置。
+
+初始化脚本和手动操作默认遇到错误便停止后续执行。Windows 使用 PowerShell，并检查 Git 等外部程序的非零退出码；其他平台使用 `sh -e`。显式条件判断、错误捕获和管道仍遵循对应 shell 的控制规则。停止不会撤销先前已经成功的命令。
+
+## 安装
+
+本插件随 dsh-plugin-lab 开发，使用本地目录安装：
+
+~~~powershell
+dsh plugin --profile desktop add <插件目录>
+~~~
+
+安装后刷新 DSH 网页版；桌面版需要由用户自行完成最终验收。
+
+## 数据与安全边界
+
+- 工作树默认位于仓库主工作树的 .agents/worktrees/；面板内可设置其他绝对路径，仅影响之后创建的工作树。
+- 插件状态和归档 Git 引用保存在仓库的 Git common directory 下 dsh-worktree-control/ 与 refs/dsh-worktree-control/archive/。
+- 环境配置、默认项、新对话草稿与对话选择记录保存在同一个仓库的 Git common directory 下，所有附加工作树共享。
+- 快照保存 Git 已跟踪改动、非忽略未跟踪文件、未推送提交可达的历史，以及 .worktreeinclude 明确列出的文件。其他被忽略文件不会进入快照。
+- 含子模块或未解决冲突的工作树不能归档。归档、恢复和删除快照均在操作前验证目标。
+- 初始化脚本只在用户勾选/点击后运行；它在新工作树目录执行。创建 PR 需要已安装并登录 GitHub CLI（gh）。
+- 交接复制源目录相对共同祖先的成果，源目录和目标分支引用保持原样。目标必须没有未提交改动且能无冲突应用，带入内容作为暂存改动。
+- 目录切换使用 DSH 原生工作目录服务，不更换会话，也不重建右侧标签；已有进程继续使用原来的目录。
+- 快照不会保留暂存与未暂存的原始分界。恢复后使用 detached HEAD；需要推送时可在面板中创建分支。
+- 自动保留无法确认安全时只显示提示，不强制删除工作树。
+
+## 开发
+
+~~~powershell
+npm test
+~~~

package/README_EN.md

@@ -0,0 +1,61 @@
+# Git Worktree Control
+
+A DSH right-sidebar panel for managing Git worktrees. Switching a worktree only changes the current conversation's working directory, so the conversation history stays continuous.
+
+## Features
+
+- Create a detached worktree from HEAD or a local/remote branch, optionally creating a new branch.
+- The native branch button below an assistant reply offers a regular conversation fork in the current workspace or a fork in a newly created worktree. The worktree option immediately creates and opens the fork, copying uncommitted changes by default; it explains when Git, session state, or read-only access prevents creation.
+- New conversations have a compact picker for creating a worktree, choosing its base ref, and selecting a local environment. Creation occurs on the first prompt; detailed controls remain in the sidebar.
+- A fork marker identifies conversations in any Git linked worktree and follows their current directory.
+- With sidebar-chat, promoting a side chat preserves its project and working directory and registers it as another conversation in the same worktree. Both conversations share files; archiving one preserves the tree while the other still uses it.
+- Optionally copy staged, unstaged, and untracked changes into the new worktree without changing the source checkout.
+- Copy ignored local files matched by .gitignore-style .worktreeinclude patterns, plus ignored AGENTS.override.md files. Existing destination files are preserved; symlinks and escaping paths are rejected.
+- Save, edit, delete, and switch multiple local project environments, including a default and per-conversation selection. Copy .codex/environments/environment.toml into an editable environment when needed.
+- Run the selected environment's setup script after creating a worktree; manually run project actions. If setup fails, the first message still proceeds in the new worktree and the details panel shows the failure. Switching an existing conversation's environment does not rerun setup.
+- Switch the same conversation between the local checkout and Git worktrees, or hand off changes to the local checkout or the conversation's previous worktree.
+- Inspect changes and stage, unstage, or discard files; commit staged changes, push branches, and open the GitHub CLI PR flow.
+- Snapshot before archiving and restore a snapshot later.
+- Archiving a loaded conversation snapshots its associated worktrees when no other unarchived conversation uses them. Pinned worktrees are preserved; old trees associated with unloaded conversations are handled later by retention cleanup.
+- Configure a per-repository retention limit (default 15; 0 disables automatic cleanup). Pinned, current, and active-session worktrees are skipped.
+
+## Environment commands
+
+The compact run menu beside Changes lists the current environment's manual actions, with Switch environment and Manage environments entries. It is hidden outside Git working directories. Selecting another environment does not rerun setup.
+
+Menu actions, detail-panel commands, and automatic setup for new worktrees open DSH's built-in sidebar terminal with live command output and results in the target worktree. Selecting a running action focuses its terminal instead of launching it twice. Logs remain after completion; each later run opens a fresh terminal, so close completed terminals to free slots. Ctrl+C, the menu's Stop action, and closing the execution terminal stop the command. Manual actions support long-running development servers; setup retains a ten-minute timeout.
+
+Enable the built-in terminal and make Node.js available on the local PATH. Actual commands retain the conversation's permission restrictions. Setup starts only after the terminal connects; a 45-second launch timeout reports a failure and preserves the created worktree. While a command is active, this plugin prevents Git mutations, switching, and cleanup of that worktree.
+
+Manual actions have separate name and multiline command fields. Enter inserts a newline; pasted scripts keep their line breaks after saving. Commands share one script scope and run in the current worktree directory.
+Saving ignores actions whose name and command are both empty or whitespace-only. Incomplete actions show their row number and missing field, and focus that input. Failed saves preserve the form and the previously saved configuration.
+
+Setup scripts and manual actions stop on errors by default. Windows uses PowerShell with explicit nonzero-exit checks for native programs such as Git; other platforms use `sh -e`. Explicit conditions, error handling, and pipelines retain their shell's control-flow semantics. Stopping does not undo commands that already succeeded.
+
+## Install
+
+This plugin is developed in dsh-plugin-lab and can be installed from a local directory:
+
+~~~powershell
+dsh plugin --profile desktop add <plugin-directory>
+~~~
+
+Refresh the DSH web app after installation. The user performs final desktop-app acceptance.
+
+## Data and safety
+
+- Worktrees default to .agents/worktrees/ in the primary checkout. A different absolute root can be configured in the panel for future worktrees.
+- State and archive refs are stored in the repository's Git common directory under dsh-worktree-control/ and refs/dsh-worktree-control/archive/.
+- Snapshots preserve tracked changes, non-ignored untracked files, reachable commits, and files explicitly listed in .worktreeinclude. Other ignored files are excluded.
+- Worktrees with submodules or unresolved conflicts cannot be archived. Targets are checked before archive, restore, and snapshot deletion.
+- Setup scripts run only after an explicit user choice. Pull request creation requires an installed and authenticated GitHub CLI (gh).
+- Handoff copies changes relative to the common ancestor without modifying the source checkout or moving the target branch. The target must be clean and accept the changes without conflicts; imported changes are staged.
+- Directory changes use DSH's working-directory service and preserve conversation and sidebar-tab identity. Existing processes keep their original directories.
+- Snapshots do not preserve the original staged/unstaged boundary. Restoration uses a detached HEAD; create a branch in the panel before pushing.
+- Automatic cleanup reports when no safe candidate is available instead of forcibly deleting a worktree.
+
+## Development
+
+~~~powershell
+npm test
+~~~