dsh-shipgate

Readme

# ShipGate

ShipGate is a local-first, pre-merge receipt generator. It reads an explicit Git comparison and caller-supplied check evidence, then writes a deterministic JSON Release Receipt and portable Markdown summary. It does not execute checks, upload source code, or claim that code is correct.

## Local Development

Requires Node.js 20 or newer.

```sh
cd /Users/albert.liu/Projects/dsh-delivery-gate/shipgate
npm install
npm test
```

## Usage

Run the built CLI from the Git repository being evaluated:

```sh
node /Users/albert.liu/Projects/dsh-delivery-gate/shipgate/dist/cli.js inspect \
  --base origin/main \
  --checks checks.json \
  --intent "Add checkout validation"
```

The default outputs are `.shipgate/receipts/<head-sha>/receipt.json` and `summary.md`. Local mode is advisory. Add `--ci` to apply the project's configured failure policy.

`checks.json` records observed check results and is never executed:

```json
{
  "schemaVersion": "1.0",
  "checks": [
    {
      "id": "unit-tests",
      "label": "Unit tests",
      "status": "passed",
      "command": "pnpm test",
      "exitCode": 0
    }
  ]
}
```

Optional `.shipgate.yml` configuration declares required check IDs, disabled or severity-overridden rules, CI failure conditions, and path-redaction patterns. Its detailed contract is in [DESIGN.md](./DESIGN.md).

## GitHub Action

Action 已内置于此目录，会在用户自己的 GitHub runner 中执行，不上传源码或 Receipt。使用时必须让 `actions/checkout` 拉取完整历史，以便解析 merge base：

```yaml
name: ShipGate

on:
  pull_request:

jobs:
  shipgate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: ./shipgate
        id: receipt
        with:
          base: ${{ github.event.pull_request.base.sha }}
          checks: checks.json
      - uses: actions/upload-artifact@v4
        with:
          name: shipgate-receipt
          path: .shipgate/receipts
```

Action 输出 `receipt-id`、`outcome`、`risk-level`、`receipt-path` 和 `summary-path`。默认会按 `.shipgate.yml` 的 `policy.failOn` 在 CI 中失败；传入 `fail-in-ci: "false"` 可改为建议性模式。

The product boundary and validation criteria remain in [PROJECT.md](./PROJECT.md).

## DSH Plugin / DSH 插件

ShipGate can be mounted as a DeepSeek Harness bundle. The plugin injects the DSH `tools` service and registers one tool: `shipgate_inspect`. It accepts an explicit Git base and optional evidence/config/output paths, then reuses the same local `inspect` core as the CLI. It never runs a command supplied by the model and never uploads source code.

The bundle metadata is in `package.json`; its patch is [cordis.patch.yml](./cordis.patch.yml). Install it according to your DSH bundle workflow, then invoke `shipgate_inspect` with at least:

```json
{
  "base": "origin/main",
  "checks": "checks.json",
  "ci": true
}
```

The tool returns the receipt ID, outcome, risk level, artifact paths, and the Markdown summary. `ci: false` (the default) keeps a failed policy result advisory, consistent with the CLI.