worktree-mgr 简体中文 A plugin that provides task-isolated workspaces for dsh (DeepSeek Harness, a plugin-based harness running on the Cordis plugin framework). When a model processes multiple tasks in parallel, each task is completed in its own git workspace (git worktree) on its own branch, without polluting the main workspace; when the task ends, the plugin commits, merges, and cleans up automatically. The full lifecycle — create / sync / overview / finish / batch cleanup — is covered by 5 tools + 1 CLI, with zero manual git operations throughout. ## Core Concepts | Concept | Description | |------|------| | Task | A single unit of work, e.g. add-search-box. Tools take the task name as entry point | | Branch | Derived automatically from the task name: <prefix>/<task-slug>, default wtm/add-search-box, or explicitly specified | | Workspace | Located under the vault directory (default platform data dir wtm/vaults/<repo-slug>/), isolated from the main repository | | Ledger | index.json under the vault, persisting the "task ↔ branch ↔ path" mapping (JSON format, atomic writes + mutex lock) | | Base branch | The branch a task merges into; defaults to the main workspace's current branch | ## Features - Task-driven: give the model a task name and the branch name, path, and ledger record are all generated automatically — no need to specify a branch - Branch name safety: task name → slug normalization (illegal forms such as .. within a segment, .lock suffix, leading dots in a segment are fixed at the source), with dual ref-validity checks; creation is rejected when different tasks derive the same slug - Uncommitted change detection: merge is refused when the base branch is dirty (prevents mixing in unfinished work); uncommitted changes in the task workspace trigger an automatic snapshot commit by default - Merge target consistency: before merging, the plugin validates "main workspace current branch == ledger base branch" and "task workspace current branch == ledger task branch"; any mismatch is refused — eliminating the silent error of reporting success while changes land on the wrong branch - Sync and finish separated: wtm_merge only merges without cleanup, while wtm_finish commits → merges → deletes workspace → deletes branch → clears the record; retry scenarios automatically skip already-completed merges (no duplicate empty merge commits) - Batch cleanup: wtm_purge finishes multiple tasks at once; a single task failure does not interrupt the rest, and any failure yields a non-zero exit code - Repository-level configuration: <repo-root>/.wtm.json supports branch prefixes, message templates, seed files (with path-escape protection), and lifecycle triggers (fixed working directory) - Concurrency safety: ledger writes hold a mutex — the lock contains a unique token with heartbeat refresh, stale locks are reclaimed only after a process crash, and release never mistakenly deletes a successor's lock - Failure recovery: a failed create rolls back the created worktree and branch automatically; merge conflicts provide a git merge --abort recovery guide - Cross-platform: triggers execute on Windows (cmd) and POSIX (sh); path comparison normalizes case and separators - Zero dependencies, no build: pure Node ESM, node >= 21 is enough — install and use ## Installing in DSH Install the latest version into a profile from GitHub: bash dsh plugin --profile demo add github:JohnXu22786/worktree-mgr Remove it: bash dsh plugin --profile demo remove worktree-mgr ### Option 1: install as a dsh bundle (recommended) From a directory containing this package: bash dsh plugin --profile demo add ./worktree-mgr - package.json declares dsh.bundle.patch → cordis.patch.yml, so dsh automatically inserts the plugin line into the profile's configuration layer; - That layer defaults to root: !!js process.cwd() (the dsh startup directory as the main repository), overridable as needed; - This package is pure JavaScript with no build step, so installing from git never misses build artifacts. ### Option 2: overlay loading (without installing into a profile) bash dsh --profile demo --patch ./examples/overlay.yml overlay.yml shares the same structure as the plugin line configuration, suitable for temporary mounting or configuration tweaks. ### Option 3: standalone CLI bash npm link # or node bin/wtm.js ... wtm begin "Add Search Box" ## Quick Start bash # 1. Create an isolated workspace for the task (auto-derives branch wtm/add-search-box) wtm begin "Add Search Box" # 2. Edit code freely inside <vault>/add-search-box # (or let the model work inside the task workspace directory) # 3. View the status of all tasks (dirty/ahead/behind) wtm status # 4. Sync only, without finishing: merge task changes back to the base branch, keeping the workspace wtm merge "Add Search Box" # 5. Finish: snapshot commit → merge → remove workspace → delete branch → clear ledger wtm finish "Add Search Box" # 6. Batch finish wtm purge "Task A" "Task B" # specified tasks wtm purge --all # all tasks All commands support --json for structured output, making them easy to consume from scripts and the harness. ## CLI Reference bin/wtm.js runs standalone (wtm after npm link, or node bin/wtm.js); every subcommand accepts --json for structured output on stdout. | Command | Description | Exit code | |------|------|------| | wtm begin <task> | Create an isolated workspace (--base, --branch, --note, --root) | 0 success / 1 failure | | wtm merge <task> | Merge the task branch back to the base, keep the workspace (--mode, --message) | 0 / 1 | | wtm finish <task> | Finish and clean up (--mode, --message) | 0 / 1 | | wtm status | Overview of all tasks | 0 / 1 | | wtm purge [task...] | Batch finish; --all for everything | 0, or 1 when any task fails | | wtm help | Print usage | 0 (2 for a bare wtm) | Exit codes: 0 success; 1 operation failure (with --json the failure lives in the JSON payload, and any failed sub-result of purge also yields 1); 2 usage errors (unknown or missing command). The WTM_* environment variables apply to the CLI as well. ## Tool Interface (Model-Facing) | Tool | Purpose | Key parameters | |------|------|----------| | wtm_begin | Create an isolated workspace for a task | task(required), base, branch, note, root | | wtm_merge | Sync: merge task branch back to base branch (workspace kept) | task(required), mode(commit/refuse), message, root | | wtm_finish | Finish: commit→merge→clean up workspace and branch | task(required), mode(commit/abandon/keep), message, root | | wtm_status | Task overview (existence/dirty state/ahead-behind) | root | | wtm_purge | Batch finish | tasks, all, mode, message, root | mode semantics - commit (default): first snapshot-commit the uncommitted changes in the task workspace, then merge back to the base branch, then clean up - refuse: refuse directly when the task workspace has uncommitted changes (only wtm_merge) - abandon: discard all task changes, force-clean the workspace and delete the branch (irrecoverable, use with care) - keep: only release management; workspace and branch remain untouched (only wtm_finish) Safety boundaries (identical for tools and CLI): - Base branch workspace has uncommitted changes → merge refused (wtm_merge / wtm_finish in commit mode) - Main workspace current branch ≠ ledger base branch, or task workspace current branch ≠ ledger record → operation refused (prevents changes landing on the wrong branch) - Task branch already exists, task already registered, workspace directory already exists, or different tasks deriving the same workspace path → creation refused - Illegal task or branch name (git ref rules) → refused before any git operation - Seed file path escapes (../x escaping the repo/workspace) → intercepted with a warning - Call cancelled (exec.signal abort) → clean return; a failed create rolls back created worktrees and branches automatically ## Plugin Integration Notes (how the harness loads it) This plugin follows dsh's standard plugin protocol, consisting of three pieces: worktree-mgr/ ├── package.json # ① dsh.bundle manifest: declares this package as a configuration layer ├── cordis.patch.yml # ② Configuration layer content: inserts the plugin line into the profile ├── index.js # ③ Entry module: exports name / inject / apply └── src/ # Implementation: naming/config/vault/git/triggers/ops/tools ① Bundle manifest (package.json): json { "name": "worktree-mgr", "type": "module", "main": "index.js", "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } } ② Configuration layer (cordis.patch.yml): yaml - insert: - id: worktree-mgr name: worktree-mgr # resolved by package name; Node module resolution finds index.js config: root: !!js process.cwd() ③ Entry module (index.js) exports: js export const name = 'worktree-mgr' export const inject = ['tools'] // declares dependency on the tools registry export function apply(ctx, config = {}) { ctx.tools.register(...) // registers the 5 tools } Loading order: profile assembly → this bundle's patch layer inserts the plugin line → the loader waits for the tools service → calls apply(ctx, config) → tool schemas flow into the system prompt automatically, and the model can invoke them. Tool definition shape (consistent with dsh tool conventions): js { name: 'wtm_status', description: '...', // model-visible description parameters: { // flat property table; required: true means mandatory root: { type: 'string', description: 'repository path' } }, output: { schema: { type: 'object', properties: { ok: { type: 'boolean', required: true }, ... } }, render: (args, value) => [{ type: 'text', text: '...' }] // model-visible content }, async execute(args, exec) { ... } // returns canonical JSON; exec.signal supports cancellation } Events/hooks interface: the plugin itself does not subscribe to harness events; lifecycle extensions go through triggers in the repository-level configuration — at the on_begin / on_merge / on_finish nodes, repo-configured shell commands run with WTM_TASK / WTM_BRANCH / WTM_BASE / WTM_PATH / WTM_ROOT environment variables injected. Triggers have fixed working directories: on_begin runs inside the new workspace, on_merge / on_finish run at the main repository root. Trigger failures only log warnings and never interrupt the main flow. ## Configuration Precedence (low → high): built-in defaults < plugin line config < repo .wtm.json < environment variables WTM_* | Key | Default | Description | |----|------|------| | root | process.cwd() | Main repository path (plugin line / tool parameter only) | | vault | platform data dir wtm/vaults/<repo-slug>/ | Directory for task workspaces and the ledger; relative paths resolve against the repo path | | prefix | wtm | Branch prefix; derived branches are <prefix>/<slug> | | commitMessage | chore(wtm): snapshot {task} | Snapshot commit template, placeholders {task} {branch} {base} | | mergeMessage | merge(wtm): fold {task} into {base} | Merge commit template | Environment variables: WTM_ROOT (effective for both tools and CLI), WTM_VAULT, WTM_PREFIX, WTM_COMMIT_MESSAGE, WTM_MERGE_MESSAGE (WTM_ROOT has lower precedence than tool parameters and plugin config). ### Repository-level config <repo-root>/.wtm.json json { "prefix": "wtm", "vault": "D:/wtm-vaults", "commitMessage": "chore(wtm): snapshot {task}", "mergeMessage": "merge(wtm): fold {task} into {base}", "seed": { "files": ["docs/AGENTS.md"] }, "triggers": { "on_begin": ["pnpm install"], "on_merge": ["pnpm lint"], "on_finish": [] } } - vault must be outside the repository working tree (otherwise the vault directory would keep dirtying the main workspace, and the plugin refuses outright); - seed.files: files copied from the main repository into the workspace when the task workspace is created (e.g. team convention docs); paths must stay within the repo/workspace — out-of-bounds entries are intercepted with a warning; - triggers.*: lifecycle hook command arrays, see "Events/hooks interface" above. Unknown keys produce a warning and are ignored; a corrupted .wtm.json never blocks operations, only warns. ## Security Notes (Important) - Repository config is code: .wtm.json's seed.files copies files from the repo into workspaces, and triggers.* runs arbitrary shell commands with your user's privileges. Only enable this plugin in trusted repositories — when cloning and operating on untrusted repositories, a repo-supplied .wtm.json is equivalent to granting it your execution permissions. Leave seed/triggers empty when you don't need this capability. - Snapshot commits include untracked files: when the task workspace is dirty, the default snapshot git add -A commits everything (including untracked files such as build artifacts). To keep large directories out of history, maintain a .gitignore in the task workspace, or handle it manually with refuse mode. - abandon is irrecoverable: wtm_finish --mode abandon and batch wtm_purge force-delete workspaces and delete task branches (-D); changes there cannot be recovered, so only use them when you have confirmed the discard. ## Ledger and Concurrency - Ledger: <vault>/index.json, {version: 1, records: [{task, branch, base, path, createdAt, updatedAt, note?}]} - Writes are atomic (temp file + rename) and hold a .lock mutex for the entire operation; - The lock contains a unique holder token with a 30s heartbeat refresh: after a process crash, a lock older than 5 minutes is deemed stale and reclaimed; release validates the token so a successor's lock is never mistakenly deleted; the wait timeout defaults to 5 seconds. ## Development and Testing bash npm test # node --test, zero third-party dependencies npm run typecheck # optional: requires dev-installed typescript + @types/node Test coverage: naming rules, config merging, ledger (atomic writes/lock/stale reclamation/corruption recovery), git output parsing, triggers, lifecycle orchestration (fake git injection), tool schemas, plus integration tests against real git (full begin → modify files → status → finish chain). ## Directory Structure worktree-mgr/ ├── package.json # bundle manifest + metadata ├── cordis.patch.yml # plugin configuration layer ├── index.js # dsh plugin entry (name/inject/apply) ├── bin/wtm.js # standalone CLI ├── README.md # documentation (EN) ├── README.zh.md # documentation (ZH) ├── LICENSE # MIT license ├── src/ │ ├── naming.js # task name → branch mapping and ref validation │ ├── config.js # config merging and template rendering │ ├── vault.js # ledger persistence (atomic writes/lock) │ ├── git.js # git execution layer and output parsing │ ├── triggers.js # lifecycle triggers │ ├── ops.js # lifecycle orchestration (begin/merge/finish/status/purge) │ └── tools.js # dsh tool definitions ├── examples/ │ ├── .wtm.json.example # repository config example │ └── overlay.yml # dsh overlay example └── tests/ # node:test unit + integration tests ## License MIT — see LICENSE.