dsh-pr-guardian

Readme

# 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.

```sh
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

```sh
# 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:

```sh
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

```sh
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.

```bash
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

```text
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.