@diffpal/diffpal-win32-x64 0.1.5 → 0.1.7

package/README.md

@@ -1,82 +1,103 @@
 # DiffPal
 
-DiffPal reviews pull request diffs and publishes policy-aware feedback back to
-your CI system.
+[![ci](https://github.com/diffpal/diffpal/actions/workflows/ci.yml/badge.svg)](https://github.com/diffpal/diffpal/actions/workflows/ci.yml)
+[![diffpal-dev review](https://github.com/diffpal/diffpal/actions/workflows/diffpal-dev-review.yml/badge.svg)](https://github.com/diffpal/diffpal/actions/workflows/diffpal-dev-review.yml)
+[![npm](https://img.shields.io/npm/v/@diffpal/diffpal?label=npm)](https://www.npmjs.com/package/@diffpal/diffpal)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-It is built for teams that want AI review output that is easy to scan:
+**Diff-first AI review for pull requests.**
 
-- 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
+DiffPal turns changed code into structured findings, clear PR summaries, inline
+comments, and merge gates across GitHub, GitLab, and Azure DevOps. Bring the
+review agent your team already trusts: Codex, Copilot, OpenCode, Gemini, Claude
+Code, a hosted provider, or any ACP-compatible CLI.
 
-## Quick Start
+| Works with | Publishes | Gates on |
+| --- | --- | --- |
+| GitHub Actions, GitLab CI, Azure Pipelines | summaries, inline comments, checks/statuses, SARIF, Code Quality | policy thresholds through native CI checks and PR statuses |
 
-Add a DiffPal config, add a provider secret, then choose the CI example for your
-platform.
+[Quickstart](docs/quickstart.md) · [CI examples](docs/ci-examples.md) · [Config reference](docs/config-reference.md) · [Provider recipes](examples/README.md)
 
-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.
+## How DiffPal Works
 
-## Config
+```text
+pull request diff
+  -> DiffPal config and policy
+  -> selected ACP or hosted provider
+  -> structured findings bundle
+  -> platform publisher and CI artifacts
+```
 
-Commit `.config/diffpal/config.yaml`:
+DiffPal owns the diff collection, finding schema, gating, and platform publish
+logic. Your provider owns the model, tool loop, account, and credentials. That
+split keeps CI setup predictable while still letting you choose the agent stack
+your team already trusts.
 
-```yaml
-version: v1
+## Quick Start: GitHub Actions
 
-runtime:
-  providers:
-    codex-acp:
-      type: codex_acp
-      codex_acp:
-        reasoning_effort: low
+This is the fastest production-shaped setup: DiffPal installs itself through the
+GitHub Action, Codex is used as the review provider, and `OPENAI_API_KEY` stays
+in GitHub Secrets.
 
-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
+1. Add the config:
+
+```bash
+mkdir -p .config/diffpal
+cp examples/configs/codex-api-key/config.yaml .config/diffpal/config.yaml
 ```
 
-Add `OPENAI_API_KEY` as a CI secret so the Codex CLI can act as the
-review provider. Platform publish tokens are CI-specific:
+2. Add a repository secret:
 
-| Platform | Publish token |
+| Secret | Purpose |
 | --- | --- |
-| GitHub Actions | built-in `GITHUB_TOKEN` |
-| GitLab CI | built-in `CI_JOB_TOKEN` or `GITLAB_TOKEN` |
-| Azure Pipelines | built-in `SYSTEM_ACCESSTOKEN` |
+| `OPENAI_API_KEY` | Authenticates Codex for the review provider. |
+
+3. Add the workflow:
+
+```bash
+mkdir -p .github/workflows
+cp examples/ci/github-actions/codex-api-key.yml .github/workflows/diffpal.yml
+```
+
+4. Open a same-repository pull request.
+
+Expected result:
+
+- a `diffpal-checks` check run
+- a `DiffPal Review Summary` PR comment with an overview of the change
+- inline comments only for actionable findings
+- `.artifacts/diffpal/findings.json` in the job workspace
+- a failed job only when `gate: true` and blocking findings exist, or when setup
+  or publishing fails
+
+The examples pin package versions for repeatable credentialed CI. After your
+first successful run, bump `@diffpal/diffpal`, provider CLIs, and bridge
+packages intentionally.
 
-## GitHub Actions
+## Supported CI Systems
 
-Create `.github/workflows/diffpal-review.yml`.
+Use the same `.config/diffpal/config.yaml` shape in every CI system. The host
+workflow only changes how it checks out code, installs the provider, passes the
+platform token, and runs DiffPal.
 
-The action installs the DiffPal CLI. The workflow installs only the Codex
-provider command.
+| CI system | Examples | Output surfaces |
+| --- | --- | --- |
+| GitHub Actions | [`examples/ci/github-actions`](examples/ci/github-actions) | check run, PR summary, review comments, SARIF |
+| GitLab CI | [`examples/ci/gitlab`](examples/ci/gitlab) | MR summary, discussions, Code Quality, SARIF |
+| Azure Pipelines | [`examples/ci/azure-pipelines`](examples/ci/azure-pipelines) | PR summary thread, PR threads, PR status |
+
+GitHub Actions can use the root action directly:
 
 ```yaml
-name: diffpal-review
+name: diffpal
 
 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:
+    name: review
     if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }}
     runs-on: ubuntu-latest
     permissions:
@@ -84,161 +105,208 @@ jobs:
       pull-requests: write
       checks: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
 
       - name: Install Codex provider
-        run: npm install --global @openai/codex@latest @normahq/codex-acp-bridge@latest
+        run: npm install --global @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3
 
       - 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
+      - uses: diffpal/diffpal@v0.1.7
         with:
-          diffpal-version: latest
+          diffpal-version: 0.1.7
           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
+          profile: ci
           gate: true
+          feedback: balanced
         env:
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-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.
+For full copy-paste files and host-specific notes, read
+[`docs/ci-examples.md`](docs/ci-examples.md).
 
-## GitLab CI
+## Config You Commit
 
-Add this job to `.gitlab-ci.yml`.
+DiffPal uses the current profile-based config shape. There is no legacy
+`defaults` block.
 
 ```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
+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
+  platforms:
+    github: {}
+    gitlab: {}
+    azure: {}
+
+profiles:
+  ci:
+    diffpal:
+      gate:
+        block_on: high
 ```
 
-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.
+Review checks are intentionally simple. They ask the agent what to focus on;
+DiffPal does not hardcode individual signal slugs:
+
+| Check | Finding categories the agent may return |
+| --- | --- |
+| `security` | security |
+| `bugs` | correctness, reliability |
+| `performance` | performance |
+| `best-practices` | maintainability, testing, style |
 
-## Azure Pipelines
+Use `diffpal.review.instructions`, the `instructions` action input, or
+`--instructions-file` for repository-specific review guidance.
 
-Enable **Allow scripts to access the OAuth token**, then add this to
-`azure-pipelines.yml`.
+## Bring Your Own Agent
+
+DiffPal is not a single-provider product. It delegates review to
+`diffpal.provider`, which points at a provider under `runtime.providers`.
+
+Ready-made config recipes:
+
+| Setup | Config | Secret |
+| --- | --- | --- |
+| Generic ACP CLI | [`examples/configs/generic-acp/config.yaml`](examples/configs/generic-acp/config.yaml) | provider-specific |
+| Codex API key | [`examples/configs/codex-api-key/config.yaml`](examples/configs/codex-api-key/config.yaml) | `OPENAI_API_KEY` |
+| Codex subscription auth | [`examples/configs/codex-subscription/config.yaml`](examples/configs/codex-subscription/config.yaml) | `CODEX_AUTH_JSON_B64` |
+| Copilot fine-grained PAT | [`examples/configs/copilot-github-token/config.yaml`](examples/configs/copilot-github-token/config.yaml) | `COPILOT_GITHUB_TOKEN` |
+| OpenCode ACP | [`examples/configs/opencode-acp/config.yaml`](examples/configs/opencode-acp/config.yaml) | OpenCode-specific |
+
+Use `generic_acp` for any CLI that can start an ACP stdio server:
 
 ```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)
+runtime:
+  providers:
+    my-review-agent:
+      type: generic_acp
+      generic_acp:
+        cmd: ["your-acp-cli", "acp", "--stdio"]
+
+diffpal:
+  provider: my-review-agent
 ```
 
-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.
+Common provider aliases are available when the CLI is already installed and
+authenticated:
 
-## What You Should See
+| Type | Runtime command |
+| --- | --- |
+| `codex_acp` | Codex ACP via the configured Codex bridge |
+| `copilot_acp` | Copilot ACP |
+| `opencode_acp` | `opencode acp` |
+| `gemini_acp` | Gemini ACP |
+| `claude_code_acp` | Claude Code ACP |
+| `generic_acp` | Your explicit command |
+| `openai`, `aistudio` | Hosted API providers |
+| `pool` | Ordered provider failover |
+
+## MCP Servers
 
-On pull requests, DiffPal can publish:
+DiffPal can pass MCP servers through the Norma runtime to providers that support
+them. Declare servers once, then attach them to the provider:
 
-- 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
+```yaml
+runtime:
+  mcp_servers:
+    repo-docs:
+      type: stdio
+      cmd: ["your-docs-mcp-server"]
+      args: ["--root", "."]
+      env:
+        DOCS_TOKEN: "${DOCS_TOKEN}"
+    policy-api:
+      type: http
+      url: "https://policy.example.com/mcp"
+      headers:
+        Authorization: "Bearer ${POLICY_MCP_TOKEN}"
+  providers:
+    opencode-acp:
+      type: opencode_acp
+      mcp_servers:
+        - repo-docs
+        - policy-api
+      opencode_acp:
+        model: opencode/big-pickle
+
+diffpal:
+  provider: opencode-acp
+```
+
+Keep MCP credentials in CI secrets. Use envsubst placeholders only for values
+that are guaranteed to exist in that job.
+
+## Feedback Modes
+
+Use `feedback` for the normal user-facing shape:
+
+| Mode | Behavior |
+| --- | --- |
+| `summary` | One PR/MR summary plus check/status, no inline comments. |
+| `balanced` | Summary plus actionable high-confidence inline feedback. |
+| `inline` | Summary plus a more permissive inline threshold. |
+
+Use `summary-overview: false` or `--summary-overview=false` if you do not want
+the semantic change overview in the summary.
+
+If two DiffPal workflows run on the same PR, give them separate channels:
+
+```yaml
+with:
+  review-channel: diffpal-dev
+  review-id: github-pr-${{ github.event.pull_request.number }}-diffpal-dev
+```
 
-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`.
+That produces a separate `diffpal-dev-checks` check run and separate summary
+comment.
 
 ## Local Debugging
 
-Local commands are useful for setup checks and debugging, but they are not the
-main CI setup path.
+CI is the main path, but local checks help when wiring a provider:
 
 ```bash
-npm install --global @diffpal/diffpal@latest @openai/codex@latest @normahq/codex-acp-bridge@latest
+npm install --global @diffpal/diffpal@latest @openai/codex@0.139.0 @normahq/codex-acp-bridge@1.6.3
 printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
-diffpal init
 diffpal doctor --mode github
-diffpal review local --base origin/main --head HEAD
+diffpal review local --base origin/main --head HEAD --profile ci
 ```
 
 ## Documentation
 
 - [Quickstart](docs/quickstart.md)
 - [CI setup guide](docs/ci-examples.md)
+- [Examples](examples/README.md)
 - [Config reference](docs/config-reference.md)
 - [Findings schema](docs/findings-schema.md)
 - [GitLab adapter reference](docs/platform-gitlab.md)

package/package.json

@@ -16,5 +16,5 @@
   "os": [
     "win32"
   ],
-  "version": "0.1.5"
+  "version": "0.1.7"
 }