@yokira404/dsh-git-guard 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yokira
+
+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,106 @@
-# Temporary Holding Version
+# Git Repository Guard · dsh-git-guard
 
-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.
+Two switches at the right of the Session header that stop an agent from writing your
+local git repository or uploading it to a remote.
+
+| Switch | Position | What it blocks |
+| --- | --- | --- |
+| Local repository | left | Writes to the local repository: `git add`, `git commit`, `git reset`, `git merge`, `git tag` and friends |
+| Remote repository | right | Anything that reaches a remote: `git push`, `git pull`, `git clone`, `git remote`, `gh` and friends |
+
+Both start on. The block happens **before** a command runs: the call is not executed,
+and the agent gets a clear refusal instead.
+
+![Where the two switches sit](docs/position.svg)
+
+## Install
+
+```bash
+dsh plugin --profile <profile> add https://github.com/Yokira404/dsh-git-guard
+```
+
+Reload the page and the two switches appear at the right of the Session header.
+
+> By hand: add `@yokira404/dsh-git-guard` to `dsh.profile.bundles` in
+> `~/.dsh/profiles/<profile>/package.json`, and point `dependencies` at this package.
+
+## How the two switches interact
+
+Two rules, both the **consequence of a click** — never a condition that has to hold:
+
+| Click | Local | Remote |
+| --- | --- | --- |
+| left (local) | toggles | turns **on** with the local switch when that lands on; left alone when it lands off |
+| right (remote) | turns **off** with the remote switch when that lands off; left alone when it lands on | toggles |
+
+- **Switching a guard on never releases the other one.** Asking for one protection must not dismantle the other.
+- **Releasing the upload guard releases the local one with it** — the local writes are exactly what an upload would carry.
+- One deliberate opening: **with both off, the right switch arms the upload guard alone**, leaving local writes open.
+
+All four states are reachable:
+
+| State | Local writes | Uploads |
+| --- | --- | --- |
+| on · on (default) | blocked | blocked |
+| off · on | allowed | blocked |
+| on · off | blocked | allowed |
+| off · off | allowed | allowed |
+
+## What is blocked
+
+**Left switch** — writes to the local repository:
+
+```
+git add · git commit · git am · git apply · git checkout-index · git config
+git merge · git mv · git notes · git rebase · git reset · git restore
+git revert · git rm · git stash · git switch · git tag
+git update-index · git update-ref
+```
+
+**Right switch** — anything that reaches a remote:
+
+```
+git push · git pull · git fetch · git clone · git ls-remote · git remote
+git submodule · git send-pack · git archive · git request-pull · git svn
+gh repo / pr / release / issue / run / workflow / api / gist / secret / …
+a repository URL on the command line (github.com, gitlab.com, gitee.com, …)
+```
+
+**Never blocked**: `git status`, `git log`, `git diff`, `git show`, `git branch`,
+`git blame`, `git init`, `git rev-parse`, `git check-ignore`, `git ls-files`,
+`git worktree`, `git help`, `gh auth`, `gh config`, `gh api /user`, and anything that is
+not about git at all. `git init` is allowed on purpose: creating a repository neither
+commits nor uploads anything.
+
+Matching is **quote-aware**: `git commit -m "do not push this"` is a local commit, not
+an upload, and `echo "git push" > notes.txt` is nothing. It is not fooled by prefixes
+either — `sudo git push`, `env FOO=1 git commit` and
+`C:\Program Files\Git\cmd\git.exe push` are all recognised.
+
+## What the agent sees when it is blocked
+
+```
+已阻止：DSH 的「Git 仓库保护」插件当前开着左侧的本地仓库开关，
+写入本地仓库的操作（git add / git commit 等）被拒绝。
+被拦截的命令：`git commit -m x`
+这是用户有意设置的开关，不是故障：不要改用其他命令、其他工具或直接调用 API 绕过它，
+也不要尝试关闭该开关。请把这一步作为「未执行」如实报告给用户，
+并说明用户可以点击会话标题栏的两个方形按钮自行放行。
+```
+
+## Limits
+
+- **It never changes your repository**: no `.git/hooks`, no `git config`, blocking only.
+- **It also catches text that merely names a command**: matching reads the whole of a
+  tool call's command-like field (`command`, `script`, `code`, …), so writing a document
+  whose text contains `git push` can have that write blocked. That is the deliberate
+  bias — one extra blocked write beats one upload that got through.
+- **It cannot stop paths that avoid the shell**; it targets the real one, an agent
+  uploading a repository through a command.
+- **No undo**: the block is up front, so there is no window in which something was
+  already uploaded.
+- **State is not persisted**: a DSH restart returns both switches to on.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,91 @@
+# Git 仓库保护 · dsh-git-guard
+
+会话标题栏右侧的一对开关，拦住 agent 写入本地 git 仓库或把它上传到远端。
+
+| 开关 | 位置 | 拦住什么 |
+| --- | --- | --- |
+| 本地仓库 | 左 | 写入本地仓库的操作：`git add`、`git commit`、`git reset`、`git merge`、`git tag` 等 |
+| 远端仓库 | 右 | 触达远端的操作：`git push`、`git pull`、`git clone`、`git remote`、`gh` 等 |
+
+两个都默认开启。拦截发生在命令真正执行**之前**，被拒绝的操作不会执行，agent 会收到明确的拒绝理由。
+
+![两个开关的位置](docs/position.svg)
+
+## 安装
+
+```bash
+dsh plugin --profile <profile> add https://github.com/Yokira404/dsh-git-guard
+```
+
+装好后重新加载页面，即可在会话标题栏右侧看到这两个开关。
+
+> 手动登记 profile 也可以：在 `~/.dsh/profiles/<profile>/package.json` 的 `dsh.profile.bundles` 里加上 `@yokira404/dsh-git-guard`，并在 `dependencies` 里指向本包。
+
+## 开关怎么联动
+
+两者的关系只有两条，都是**一次点击的后果**，没有「必须一直成立」的约束：
+
+| 点击 | 本地 | 远端 |
+| --- | --- | --- |
+| 左（本地） | 取反 | 本地变成**开**时，远端跟着**开**；本地变成关时，远端不动 |
+| 右（远端） | 远端变成**关**时，本地跟着**关**；远端变成开时，本地不动 | 取反 |
+
+- **打开一侧永远不会关掉另一侧**：打开一个保护，不该顺手拆掉另一个保护。
+- **关闭远端会连带关闭本地**：本地写入正是上传要带走的东西，只放开远端等于留着一半。
+- 特例：**两个都关时点右侧**，只打开远端、本地保持关闭。这是有意留的口子 —— 只拦上传、不拦本地写入。
+
+四种状态都可达：
+
+| 状态 | 本地写入 | 上传远端 |
+| --- | --- | --- |
+| 开 · 开（默认） | 拦 | 拦 |
+| 关 · 开 | 放行 | 拦 |
+| 开 · 关 | 拦 | 放行 |
+| 关 · 关 | 放行 | 放行 |
+
+## 判定范围
+
+**会被拦 · 左开关** —— 写入本地仓库：
+
+```
+git add · git commit · git am · git apply · git checkout-index · git config
+git merge · git mv · git notes · git rebase · git reset · git restore
+git revert · git rm · git stash · git switch · git tag
+git update-index · git update-ref
+```
+
+**会被拦 · 右开关** —— 触达远端：
+
+```
+git push · git pull · git fetch · git clone · git ls-remote · git remote
+git submodule · git send-pack · git archive · git request-pull · git svn
+gh repo / pr / release / issue / run / workflow / api / gist / secret / …
+命令行上直接出现 github.com、gitlab.com、gitee.com 等仓库地址
+```
+
+**不会被拦**：`git status`、`git log`、`git diff`、`git show`、`git branch`、`git blame`、`git init`、`git rev-parse`、`git check-ignore`、`git ls-files`、`git worktree`、`git help`、`gh auth`、`gh config`、`gh api /user`，以及任何与 git 无关的命令。`git init` 是有意放行的：建仓库既不上传也不提交。
+
+判定是**引用感知**的：`git commit -m "do not push this"` 是本地提交，不是上传；`echo "git push" > notes.txt` 什么都不是。判定也不吃前缀：`sudo git push`、`env FOO=1 git commit`、`C:\Program Files\Git\cmd\git.exe push` 都能识别出来。
+
+## 被拦时 agent 看到什么
+
+```
+已阻止：DSH 的「Git 仓库保护」插件当前开着左侧的本地仓库开关，
+写入本地仓库的操作（git add / git commit 等）被拒绝。
+被拦截的命令：`git commit -m x`
+这是用户有意设置的开关，不是故障：不要改用其他命令、其他工具或直接调用 API 绕过它，
+也不要尝试关闭该开关。请把这一步作为「未执行」如实报告给用户，
+并说明用户可以点击会话标题栏的两个方形按钮自行放行。
+```
+
+## 已知限制
+
+- **不改动你的仓库**：不写 `.git/hooks`，不碰 `git config`，只做拦截。
+- **会误伤「正文里写着命令名」的调用**：判定看的是工具调用里命令类字段（`command` / `script` / `code` 等）的整串文本，所以用 `write` 写一份含 `git push` 字样的文档时，那次写入本身可能被拦。这是有意的偏向 —— 宁可多拦一次写入，也不放过一次上传；换个写法即可正常写入。
+- **拦不住不走 shell 的路径**：它针对的是 agent 通过命令上传仓库这条真实路径。
+- **不做事后撤销**：拦在事前，不存在已经推上去再回滚的窗口。
+- **状态不持久化**：DSH 重启后回到「两个都开启」。
+
+## 许可
+
+MIT