@diffpal/diffpal-win32-x64 0.1.1 → 0.1.3

package/README.md

@@ -1,75 +1,247 @@
 # DiffPal
 
-DiffPal is a diff-first, policy-aware review assistant.
-
-- Diff collection and review are treated as a first-class artifact (`findings.json`).
-- Review runs are mode-scoped: local review stays local, and host review emits only that host's artifacts.
-- GitHub is the primary host surface; GitLab and Azure adapters follow the same findings contract.
-
-## Package and runtime contract
+DiffPal reviews pull request diffs and publishes policy-aware feedback back to
+your CI system.
+
+It is built for teams that want AI review output that is easy to scan:
+
+- PR summaries that explain what changed
+- inline comments only for actionable findings
+- merge gates through checks/statuses, not bot approvals
+- one config file that works across GitHub, GitLab, and Azure DevOps
+
+## Quick Start
+
+Add a DiffPal config, add a provider secret, then choose the CI example for your
+platform.
+
+The examples use npm `@latest` for quick onboarding. For production, pin
+`@diffpal/diffpal`, `diffpal-version`, `@openai/codex`, and
+`@normahq/codex-acp-bridge` to versions you have tested.
+
+## Config
+
+Commit `.config/diffpal/config.yaml`:
+
+```yaml
+version: v1
+
+runtime:
+  providers:
+    codex-acp:
+      type: codex_acp
+      codex_acp:
+        reasoning_effort: low
+
+diffpal:
+  provider: codex-acp
+  gate:
+    block_on: high
+  review:
+    language: en
+    instructions: |
+      Prefer actionable findings that are directly supported by the diff.
+    checks:
+      - security
+      - bugs
+      - performance
+      # - best-practices
+```
 
-- Go module: `github.com/diffpal/diffpal`
-- CLI binary: `diffpal`
-- Default package license: `MIT`
-- Build stack: Go 1.26.4
-- CLI package: `@diffpal/diffpal`
-- GitHub Action: `diffpal/action`
-- NPM scope: `@diffpal/*`
-- Self-review: `.github/workflows/diffpal-review.yml` installs `@diffpal/diffpal@latest` and runs this repository's action on same-repository pull requests.
+Add `OPENAI_API_KEY` as a CI secret so the Codex CLI can act as the
+review provider. Platform publish tokens are CI-specific:
+
+| Platform | Publish token |
+| --- | --- |
+| GitHub Actions | built-in `GITHUB_TOKEN` |
+| GitLab CI | built-in `CI_JOB_TOKEN` or `GITLAB_TOKEN` |
+| Azure Pipelines | built-in `SYSTEM_ACCESSTOKEN` |
+
+## GitHub Actions
+
+Create `.github/workflows/diffpal-review.yml`.
+
+The action installs the DiffPal CLI. The workflow installs only the Codex
+provider command.
+
+```yaml
+name: diffpal-review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: diffpal-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Codex provider
+        run: npm install --global @openai/codex@latest @normahq/codex-acp-bridge@latest
+
+      - name: Authenticate Codex
+        run: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+      - name: Review pull request
+        uses: diffpal/diffpal@v0.1.2
+        with:
+          diffpal-version: latest
+          base: ${{ github.event.pull_request.base.sha }}
+          head: ${{ github.event.pull_request.head.sha }}
+          repo: ${{ github.repository }}
+          review-id: github-pr-${{ github.event.pull_request.number }}
+          feedback: balanced
+          gate: true
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
 
-See [docs/product-contract.md](docs/product-contract.md) for full contract details.
+The same-repository PR guard keeps provider secrets out of untrusted fork
+workflows. Remove or change that guard only after designing a fork-safe release
+flow.
+
+## GitLab CI
+
+Add this job to `.gitlab-ci.yml`.
+
+```yaml
+stages:
+  - review
+
+diffpal-review:
+  stage: review
+  image: node:22
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  resource_group: "diffpal:$CI_MERGE_REQUEST_IID"
+  before_script:
+    - npm install --global @diffpal/diffpal@latest @openai/codex@latest @normahq/codex-acp-bridge@latest
+    - printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
+  script:
+    - >-
+      diffpal review gitlab
+      --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"
+      --head "$CI_COMMIT_SHA"
+      --repo "$CI_PROJECT_PATH"
+      --review-id "gitlab-mr-$CI_MERGE_REQUEST_IID"
+      --language en
+      --review-checks security,bugs,performance,best-practices
+      --feedback balanced
+      --gate
+  variables:
+    GIT_DEPTH: "0"
+  artifacts:
+    when: always
+    paths:
+      - .artifacts/diffpal/
+    reports:
+      codequality: .artifacts/diffpal/codequality.json
+      sarif: .artifacts/diffpal/diffpal.sarif
+```
 
-## Commands
+Set `OPENAI_API_KEY` as a protected/masked CI variable. Use the built-in
+`CI_JOB_TOKEN` when your GitLab instance allows it, or set `GITLAB_TOKEN` for a
+dedicated API token.
+
+## Azure Pipelines
+
+Enable **Allow scripts to access the OAuth token**, then add this to
+`azure-pipelines.yml`.
+
+```yaml
+trigger: none
+pr:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - checkout: self
+    fetchDepth: 0
+
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "22.x"
+
+  - script: npm install --global @openai/codex@latest @normahq/codex-acp-bridge@latest
+    displayName: Install Codex provider
+
+  - script: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
+    displayName: Authenticate Codex
+    env:
+      OPENAI_API_KEY: $(OPENAI_API_KEY)
+
+  - task: DiffPalReview@1
+    displayName: DiffPal review
+    inputs:
+      diffpalVersion: latest
+      language: en
+      reviewChecks: security,bugs,performance,best-practices
+      feedback: balanced
+      gate: true
+    env:
+      OPENAI_API_KEY: $(OPENAI_API_KEY)
+      SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+```
 
-This repository includes the canonical CLI command tree:
+The Azure task installs the DiffPal CLI by default. Set `install: false` to use
+a preinstalled binary from `PATH`, or set `diffpalPath` to a custom binary path.
 
-- `diffpal review`
-- `diffpal review local`
-- `diffpal review github`
-- `diffpal review gitlab`
-- `diffpal review ado`
-- `diffpal sarif`
-- `diffpal init`
-- `diffpal doctor`
-- `diffpal version`
+## What You Should See
 
-## Repository layout
+On pull requests, DiffPal can publish:
 
-- `cmd/diffpal` contains the build entrypoint for the CLI binary.
-- `internal/cmd` contains the Cobra command tree and command wiring.
-- `internal/...` contains non-exported runtime, diff, policy, findings, platform, and reliability packages.
-- `docs/` records the product contract, config, platform adapters, and release behavior.
+- a review summary with a semantic overview of the change
+- a check/status for merge gating
+- inline comments or threads for actionable findings
+- JSON, SARIF, and CI artifacts for later inspection
 
-## Documentation
+The default review checks are `security`, `bugs`, `performance`, and
+`best-practices`. The default review language is English. Checks, language, and
+custom review instructions are configurable in `.config/diffpal/config.yaml` or
+by CLI flags such as `--review-checks`, `--instructions`, and
+`--instructions-file`.
 
-- [Quickstart](docs/quickstart.md)
-- [Config and policy reference](docs/config-reference.md)
-- [Configuration schema](docs/config-schema.md)
-- [Findings schema](docs/findings-schema.md)
-- [GitHub/GitLab/Azure CI examples](docs/ci-examples.md)
-- [GitLab adapter contract](docs/platform-gitlab.md)
-- [Azure adapter contract](docs/platform-azure.md)
-- [Release process](docs/release.md)
+## Local Debugging
 
-## First Commands
+Local commands are useful for setup checks and debugging, but they are not the
+main CI setup path.
 
 ```bash
+npm install --global @diffpal/diffpal@latest @openai/codex@latest @normahq/codex-acp-bridge@latest
+printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
 diffpal init
-diffpal doctor
+diffpal doctor --mode github
 diffpal review local --base origin/main --head HEAD
-diffpal review github --base origin/main --head HEAD --gate
-```
-
-## Development
-
-```bash
-go mod download
-go mod verify
-go test ./...
-go tool golangci-lint run ./...
-go run ./cmd/diffpal --help
 ```
 
-The npm package is the user-facing CLI distribution. Source development in this repository uses the Go toolchain directly.
+## Documentation
 
-Maintainers track project work in Beads (`bd`). External contributors do not need Beads to open issues or pull requests.
+- [Quickstart](docs/quickstart.md)
+- [CI setup guide](docs/ci-examples.md)
+- [Config reference](docs/config-reference.md)
+- [Findings schema](docs/findings-schema.md)
+- [GitLab adapter reference](docs/platform-gitlab.md)
+- [Azure adapter reference](docs/platform-azure.md)
+- [Release process](docs/release.md)
+- [Contributing](CONTRIBUTING.md)

package/package.json

@@ -16,5 +16,5 @@
   "os": [
     "win32"
   ],
-  "version": "0.1.1"
+  "version": "0.1.3"
 }