Harzva/dsh-pr-guardian

A DSH management inbox for feedback on your own pull requests, maintained by Harzva. Version 0.2.0-alpha.1 targets DSH 0.1.1-rc.2, Cordis 4.0.1, React 18.2.0 and Node 24+. Tested on macOS.

The sidebar opens a searchable feedback panel. It discovers the active gh account's authored open PRs, paginates ordinary comments, formal reviews and review threads (including nested comments), and prioritizes human feedback, favorites, CI failures and conflicts. GitHub text is data, never executable instructions.

Local progress is version-bound: edited feedback becomes pending again. Favorites and pending / investigated / awaiting_user states survive restarts; resolved threads and superseded reviews are distinguished. Raw comment bodies are hashed within the adapter and are not persisted. The management API has no GitHub write operations.

Install the release artifact

Requirements: an authenticated GitHub CLI (gh auth status), Git, Node 24+, and the exact DSH compatibility tuple above. No model API key is needed for the inbox.

dsh plugin --profile web add https://github.com/Harzva/dsh-pr-guardian/releases/download/v0.2.0-alpha.1/dsh-pr-guardian-0.2.0-alpha.1.tgz
dsh --profile web

Open PR Guardian in the sidebar, then 刷新 GitHub. The release tarball contains compiled Host, Client and Typert exports. GitHub source-shortcut installation is a separate, unverified delivery path.

Shared Codex / DSH workflow

# From this source checkout after npm ci && npm run build:
node bin/guardian-management.mjs sync
node bin/guardian-management.mjs list
# Or use guardian-management from the installed package's bin directory.

Default state: $DSH_HOME/dsh-pr-guardian/management (DSH_HOME defaults to ~/.dsh). The CLI accepts --state-dir DIR; the plugin's stateDirectory setting can point to the same directory. Use identical directories to share progress between Codex and DSH.

The CLI action command accepts one JSON argument. Favorite example:

node bin/guardian-management.mjs action '{"kind":"favorite","caseId":"owner/repo#123","favorite":true}'

Feedback progress actions require kind=progress, caseId, eventId, the exact collected version, and status=pending|investigated|awaiting_user. A stale version is rejected. Local investigated status does not resolve a GitHub discussion. Feedback read failures preserve prior evidence; PRs leaving the authored-open queue require verification before being treated as closed.

For Codex scheduling, configure an hourly local automation to run the CLI, inspect pending feedback in priority order, prepare isolated candidate fixes and record version-bound progress after diagnosis. Notify only on meaningful changes or required decisions. Scheduling is owned by Codex; the DSH panel refreshes on request and does not install a hidden timer. The development workstation's private adapter and automation are not shipped in this public package.

State files use owner-only permissions, atomic replacement and an exclusive writer lock. WRITER_BUSY means another process owns the directory. If a process crashes, verify the PID in writer.lock is no longer running before removing only that lock. Never clear management.json to resolve contention. Search is bounded to 1,000 authored open PRs and feedback pagination is bounded; exceeding limits reports failure instead of silently treating partial discovery as complete.

Verification and scope

npm ci
npm run check
npm run pack:dsh
npm run verify:dsh-offline

The offline verifier packs fresh code, installs that exact tarball in a temporary DSH_HOME, cold-starts the real Web runtime, exercises strict management RPC and version conflict rejection, checks restart persistence, removes the plugin and verifies the remaining Web profile starts. It uses synthetic metadata without calling GitHub. A separate real UI smoke test exercises authenticated feedback sync and local panel actions.

This management preview is not completion of the full repair/publish plan. Two-stage approval, general candidate execution and post-push orchestration remain planned. The legacy generated-file CLI below remains separately gated with push disabled by default. See docs/release-0.2/PLAN.md and the original development plan for the distinction.

Legacy generated-file dry-run CLI

• Discover open PRs with gh search prs.
• Optionally consume the existing Codex gh_pr_watch.py snapshot adapter.
• Dry-run rebase in a temporary clone only when GitHub reports a conflict.
• For awesome-dsh-plugin, resolve only README.md and README.zh.md by restoring the current upstream version and regenerating them.
• Record JSONL observations and produce a seven-day report.
• Ask a read-only, ephemeral Codex Agent for suggestions when deterministic policy refuses a conflict.
• Require global and repository opt-in plus an exact observed head lease before any push.

Setup

Requirements: macOS, Node.js 24+, Git, GitHub CLI, and an authenticated gh session.

gh auth login -h github.com --git-protocol ssh
npm test
node bin/dsh-pr-guardian.mjs doctor
node bin/dsh-pr-guardian.mjs monitor --once
node bin/dsh-pr-guardian.mjs report --days 7

Copy guardian.local.example.json to guardian.local.json only when a machine-local state directory, opaque localRef → absolute clone path repoMap, or external watcher command is needed. The local file is ignored by Git and must not be committed; public repository rules may contain only the opaque localRef, never the machine path.

Commands

doctor
discover
status --pr URL
analyze --pr URL
monitor --once [--pr URL] [--no-agent]
report --days 7
install-launchd
uninstall-launchd

--push exists for the later gated phase, but the shipped global and repository switches are both false. Passing the flag cannot bypass either policy gate.

Seven-day gate

Keep push disabled for at least seven natural days. Review every auto_fixable_generated observation. Enable pushing only after the report contains no misclassification, all generated candidates passed their configured checks, and a human accepts the sampled diffs.

See docs/01-需求分析.md, docs/02-架构设计.md, and docs/03-开发计划.md for the complete contract.