dsh-zgit

English | 中文

[!TIP] 第一个《世界计划》本地化知识库，为同人作者和考据党而生：SekaiSync
The first Project SEKAI localization knowledge base, built for fan creators and lore enthusiasts: SekaiSync

即将面向 DeepSeek Harness 插件生态针对性适配，欢迎各位豆腐人 Star 和共建。
Targeted adaptation for the DeepSeek Harness plugin ecosystem is coming soon. Fellow Tofus are welcome to star and contribute!

zgit — a DeepSeek Harness plugin for when the first thought about fetching source code or binary releases from a git host should not be git clone.

dsh-zgit fetches over plain HTTPS, with no git binary and no runtime dependencies:

• Source code → downloaded as a forge archive (codeload-style tar.gz/zip), extracted into a simulated checkout with .zerogit metadata — a git-like directory you can inspect, status-check, and refresh.
• Binary releases → release assets listed or downloaded straight from GitHub/GitLab/Gitee releases, with sha256 verification against shipped checksum files.
• git, simulated → zgit_ls_remote, zgit_show, zgit_ls_tree, zgit_log, zgit_diff, zgit_status reimplement the read side of git over the forge APIs.
• Anything else → zgit_download fetches any direct URL (mirrors, toolchains) into the workspace with a byte cap and optional sha256.

dsh plugin --profile web add @zukunftsholz/dsh-zgit

Tools

Tool	git analog	What it does
zgit_ls_remote	git ls-remote	Branches, tags, ref→sha resolution, default branch, latest release tag.
zgit_clone	git clone / git archive	Downloads the source archive at a ref, extracts it into the workspace as a simulated checkout (.zerogit/meta.json), supports subdir sparse extraction and explicit archive URLs (mirrors).
zgit_fetch_release	gh release download	Lists or downloads release assets (latest or a tag) with glob patterns and sha256 verification.
zgit_show	git show	Fetches one raw file at a ref (optionally saved into the workspace).
zgit_ls_tree	git ls-tree	Lists files/dirs at a ref via the forge API.
zgit_log	git log	Recent commits at a ref.
zgit_diff	git diff	Compare two refs: changed-files summary or a single-file unified diff.
zgit_status	git status + git fetch	Checks a simulated checkout against the remote: moved ref, commits behind.
zgit_download	curl	Any direct HTTPS download into the workspace, capped, with optional sha256.

Plus the human-plane command /zgit (Web UI slash menu / TUI): clone, get, show, ls, log, diff, resolve, status, download — the same operations without the model in the loop.

Forge support

• GitHub (github.com + api.github.com + codeload.github.com + raw.githubusercontent.com)
• GitLab (gitlab.com + API v4), including nested groups
• Gitee (gitee.com + API v5)
• Generic GitHub-style hosts: archive/raw URL guessing works (self-hosted Gitea/GitHub Enterprise); API-backed operations report a clear error — use archiveUrl or zgit_download.

Repo references accept owner/repo, owner/repo@ref, full https:// URLs (with @ref or /tree/ref), git@host:owner/repo.git, and ssh:// URLs.

Configuration

All config lives in the plugin row ($DSH_HOME/cordis.patch.yml, the profile patch, or an overlay):

- id: zgit
  config:
    clone: true          # per-tool toggles: lsRemote, clone, release, show,
    command: true        #   lsTree, log, diff, status, download, command
    timeoutMs: 120000
    maxArchiveBytes: 536870912      # 512 MiB clone cap
    maxDownloadBytes: 1073741824    # 1 GiB download cap
    maxFileBytes: 262144            # 256 KiB zgit_show cap
    maxTreeEntries: 5000
    maxLogCommits: 30
    maxDiffChars: 100000
    maxExtractedEntries: 100000
    workspaceRoot: ''               # fallback root (defaults to process.cwd()); tool calls prefer the calling session workspace
    userAgent: dsh-zgit/0.1.1
    tokenEnv: { github: GITHUB_TOKEN, gitlab: '', gitee: '' }   # env var names
    tokens:   { github: '', gitlab: '', gitee: '' }             # or direct values

Tokens raise API rate limits and enable private repos; the env-var name wins over a direct value.

The simulated checkout

zgit_clone produces a normal directory plus:

<dir>/
├── .zerogit/
│   ├── meta.json   # origin, ref, sha, archive URL, fetched-at, file counts
│   └── HEAD        # the pinned commit sha
└── ...             # the extracted source (root folder stripped)

zgit_status <dir> re-resolves the pinned ref remotely and reports how far the checkout fell behind. Refresh with zgit_clone (replace: true).

Safety properties

• Workspace confinement — every write is resolved inside the calling session's workspace (exec.agent.session.header.cwd), falling back to workspaceRoot for agentless callers; paths escaping the root are rejected.
• Archive hardening — path traversal (.., absolute paths, Windows reserved names) is rejected; case-insensitive collisions error; entries are capped by count and total bytes; zip entries are CRC32-verified; gzip is decompressed under a hard cap (bomb guard); symlinks are recorded and skipped (not materialized), hardlinks are copied.
• Byte caps everywhere — downloads stream with early abort when a cap is exceeded.
• No execution — archives are never executed, only extracted.

Development

The package has zero runtime dependencies (pure Node builtins: node:zlib, node:crypto, node:fs, node:http). Tests run against the installed DSH profile packages:

npm run build      # scripts/build.sh (DSH checkout + junctions + tsc) via node wrapper
npm run typecheck
npm test           # vitest: parser/glob units, tar.gz+zip extractors, forge fixtures, real-HTTP e2e, Cordis mount

License

MIT