npm - @diffpal/diffpal-win32-x64 - Versions diffs - 0.1.37 → 0.1.39 - Mend

@diffpal/diffpal-win32-x64 0.1.37 → 0.1.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -5,394 +5,104 @@
 [![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)
-**Open-source, provider-agnostic AI review for pull requests.**
+**Open-source AI pull request review that runs in your CI.**
-DiffPal is an open-source PR review system that turns changed code into
-structured findings, clear summaries, file-level feedback, artifacts, and merge
-gates. Teams bring their own AI provider or ACP-compatible CLI, so there is no
-mandatory hosted DiffPal review service and no required per-seat review
-platform.
+DiffPal is for teams that want AI review feedback without adopting a mandatory
+hosted review service. Bring Codex, Copilot, OpenCode, another supported
+provider, or any ACP-compatible agent, and keep one review workflow across
+GitHub, GitLab, and Azure DevOps.
-DiffPal exists to make AI code review something teams control, not another
-review platform they rent. It runs in your CI, uses the AI provider you choose,
-and turns every pull request into clear summaries, actionable file-level feedback,
-review artifacts, and merge gates.
+[Quickstart](docs/getting-started/github-quickstart.md) ·
+[Documentation](docs/README.md) ·
+[Security](docs/security.md) ·
+[GitHub](https://github.com/diffpal/diffpal)
-Use the provider path that already works for your team and keep the review
-workflow in your repository. DiffPal's goal is to make AI PR review portable,
-affordable, and enforceable across GitHub, GitLab, and Azure DevOps.
+## What Users Get
-| Works with | Publishes | Gates on |
-| --- | --- | --- |
-| GitHub Actions, GitLab CI, Azure Pipelines | summaries, file-level comments, checks/statuses, SARIF, Code Quality | policy thresholds through native CI checks and PR statuses |
-[Quickstart](docs/quickstart.md) · [CI examples](docs/ci-examples.md) · [Config reference](docs/config-reference.md) · [Provider recipes](examples/README.md)
-## How DiffPal Works
-```text
-pull request diff
-  -> DiffPal config and policy
-  -> selected ACP or hosted provider
-  -> structured findings bundle
-  -> platform publisher and CI artifacts
-```
-DiffPal coordinates the review workflow around the model call. Your provider
-supplies the review intelligence; DiffPal keeps PR feedback, artifacts, and
-merge policy consistent across hosts.
-Review instructions are produced by DiffPal's versioned Prompt Pack. Findings
-artifacts include the prompt id, prompt version, purpose, and findings schema
-version, so a review can be traced back to the exact prompt contract that
-generated it. See the [config reference](docs/config-reference.md#prompt-pack)
-and [findings schema](docs/findings-schema.md) for the current metadata.
-## Bring Your Own Provider
-DiffPal decouples AI review from any one vendor or hosted service. Choose
-Codex, Copilot, OpenCode, Gemini, Claude Code, a hosted API provider, an ordered
-provider pool, or any ACP-compatible CLI without rebuilding your PR review
-workflow.
+| Output | Where it shows up |
+| --- | --- |
+| PR/MR summary | GitHub reviews, GitLab summaries, Azure PR threads |
+| Actionable findings | Inline comments, discussions, or PR threads on changed lines |
+| Machine-readable artifacts | Findings JSON, summary Markdown, SARIF, and Code Quality reports |
+| Optional merge gates | CI exit status, checks, commit statuses, or PR statuses |
-That model keeps cost control with your team. DiffPal does not require a hosted
-review service or per-seat platform subscription to collect diffs, publish PR
-feedback, write artifacts, or enforce merge gates.
+## Why DiffPal
-## Quick Start: GitHub Actions
+- **Runs in your CI:** review happens in the workflow you already control.
+- **Provider choice:** use the default Codex copy-paste setup, another supported
+  provider, or an ACP-compatible agent with the same DiffPal workflow.
+- **Repository-owned configuration:** review policy, instructions, artifacts,
+  and gates live with the codebase.
+- **No mandatory hosted service:** DiffPal standardizes review output without
+  requiring a hosted DiffPal review platform.
-This is the fastest production-shaped setup using the default Codex API-key
-recipe: DiffPal installs itself through the GitHub Action, Codex is selected as
-the review provider, and `OPENAI_API_KEY` stays in GitHub Secrets. You can swap
-the provider recipe while keeping the same DiffPal review workflow.
+## Minimal GitHub Quickstart
-1. Generate the config:
+Generate a GitHub Actions config with the default Codex API-key recipe:
 ```bash
 npx -y @diffpal/diffpal@latest init --wizard --setup codex-api-key --platform github
 ```
-This writes `.config/diffpal/config.yaml` with a visible `ci` profile. Existing
-files are kept unless you pass `--force`.
+Add `OPENAI_API_KEY` as a repository secret, then copy the workflow:
-2. Add a repository secret:
-| Secret | Purpose |
-| --- | --- |
-| `OPENAI_API_KEY` | Authenticates Codex for the review provider. |
-For public open-source repositories, keep provider credentials away from fork PR
-code. GitHub's fork workflow approval settings control whether outside
-contributors' fork workflows run automatically; they do not make it safe to
-release provider secrets to fork code. Keep DiffPal's secret-backed review job
-limited to same-repository pull requests. Fork PRs should run no-secret CI only.
-3. Add the workflow:
+`OPENAI_API_KEY` is a provider credential. DiffPal runs in your CI and sends
+review input to the provider you configure, so keep this secret out of
+untrusted fork PR jobs.
 ```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:
+Open a same-repository pull request. After the first successful run, expect a
+`DiffPal Review Summary`, inline findings when actionable issues exist, and
+`.artifacts/diffpal/findings.json` in the workflow workspace.
-- a `DiffPal Review Summary` PR review with an overview of the change
-- file-level review comments 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
+For full setup details, provider alternatives, and fork PR guidance, use the
+[GitHub quickstart](docs/getting-started/github-quickstart.md).
-The GitHub Action installs the latest DiffPal CLI by default. After your first
-successful run, pin `diffpal-version`, provider CLIs, and bridge packages when
-you need fully reproducible credentialed CI.
+## Supported Integrations
-## Supported CI Systems
-Use the same `.config/diffpal/config.yaml` shape in every CI system. GitHub,
-GitLab, and Azure are publishing targets; the core workflow only changes how CI
-checks out code, installs the provider, passes the platform token, and runs
-DiffPal.
-| CI system | Examples | Output surfaces |
+| Host | Native outputs | Guide |
 | --- | --- | --- |
-| GitHub Actions | [`examples/ci/github-actions`](examples/ci/github-actions) | PR review summary, file-level 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 Action
-GitHub Actions users can install the
-[DiffPal Review action](https://github.com/marketplace/actions/diffpal-review)
-with `uses: diffpal/action@v1`. The action source and release automation live in
-the separate [diffpal/action](https://github.com/diffpal/action) repository.
+| GitHub Actions | PR review summary, file-level review comments, SARIF | [GitHub Actions](docs/integrations/github-actions.md) |
+| GitLab CI | MR summary, discussions, Code Quality, SARIF, status | [GitLab CI](docs/integrations/gitlab-ci.md) |
+| Azure Pipelines | PR summary thread, PR threads, PR status | [Azure Pipelines](docs/integrations/azure-pipelines.md) |
+| Custom CI/CD | Artifact-only review, or publishing through a supported code host | [Custom CI/CD](docs/integrations/custom-ci.md) |
-The action installs `@diffpal/diffpal` by default, then runs
-`diffpal review github`. You still own provider setup and authentication in the
-workflow, so switching provider recipes does not require switching PR review
-platforms.
+GitHub users can also install the
+[DiffPal Review action](https://github.com/marketplace/actions/diffpal-review).
+Azure users can install the
+[DiffPal Review extension](https://marketplace.visualstudio.com/items?itemName=diffpal.diffpal).
-## Azure DevOps Marketplace Extension
+## Documentation By Goal
-Azure Pipelines users can install the public
-[DiffPal Review extension](https://marketplace.visualstudio.com/items?itemName=diffpal.diffpal)
-from the Azure DevOps Marketplace and add the `DiffPalReview@1` task to PR
-validation pipelines. Extension source and release automation live in the
-separate [diffpal/azure-devops](https://github.com/diffpal/azure-devops)
-repository.
-The task installs `@diffpal/diffpal` by default, then runs `diffpal review ado`.
-You still need a committed DiffPal config, a provider credential such as
-`OPENAI_API_KEY`, `SYSTEM_ACCESSTOKEN` for PR feedback publishing, and a full git
-checkout. See the [Azure Pipelines setup guide](docs/ci-examples.md#azure-pipelines)
-for copy-paste examples.
-Example GitHub Actions workflow:
-```yaml
-name: diffpal
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
-jobs:
-  review:
-    name: review
-    # Provider credentials are only exposed to same-repository PRs.
-    # Fork PRs should run no-secret CI only.
-    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
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-      - name: Install Codex provider
-        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 }}
-      - uses: diffpal/action@v1
-        with:
-          base: ${{ github.event.pull_request.base.sha }}
-          head: ${{ github.event.pull_request.head.sha }}
-          profile: ci
-          gate: true
-          feedback: review
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-`pull_request_target` runs from the default branch of the base repository and is
-useful for trusted automation such as labeling or commenting. Do not combine it
-with checking out the PR head or running package installs, tests, build scripts,
-hooks, provider CLIs, or other fork code. That pattern can expose privileged
-tokens or secrets to untrusted code.
-If you prefer copying files manually, use
-[`examples/configs/codex-api-key/config.yaml`](examples/configs/codex-api-key/config.yaml).
-For full copy-paste files and host-specific notes, read
-[`docs/ci-examples.md`](docs/ci-examples.md).
-## Config You Commit
-DiffPal uses the current profile-based config shape. There is no legacy
-`defaults` block.
-```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.
-  platforms:
-    github: {}
-    gitlab: {}
-    azure: {}
-profiles:
-  ci:
-    diffpal:
-      gate:
-        block_on: high
-```
-DiffPal uses a fixed finding taxonomy: security, correctness, reliability,
-performance, maintainability, testing, and style. Use review instructions to
-change or extend the review scope, for example `Review for OWASP best practices
-and authz/authn regressions.`
-Severity is impact-based across all categories. The full critical/high/medium/low
-matrix is in the [config reference](docs/config-reference.md#severity-matrix).
-Use `diffpal.review.instructions`, the `instructions` action input, or
-`--instructions-file` for repository-specific review guidance.
-For large pull requests or slower providers, set `diffpal.review.timeout`
-in the selected profile, for example `profiles.ci.diffpal.review.timeout: 10m`.
-## Provider Recipes and Runtime Types
-DiffPal delegates review to `diffpal.provider`, which points at a provider
-under `runtime.providers`.
-Ready-made config recipes. These are the same names accepted by
-`diffpal init --wizard --setup ...`:
-| 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 |
-For Codex subscription auth, generate a fresh `CODEX_AUTH_JSON_B64` value with
-the command recipe in [`examples/README.md`](examples/README.md#generate-codex_auth_json_b64).
-Use `generic_acp` for any CLI that can start an ACP stdio server:
-```yaml
-runtime:
-  providers:
-    my-review-agent:
-      type: generic_acp
-      generic_acp:
-        cmd: ["your-acp-cli", "acp", "--stdio"]
-diffpal:
-  provider: my-review-agent
-```
-Common provider aliases are available when the CLI is already installed and
-authenticated:
-| Type | Runtime command |
+| Goal | Start here |
 | --- | --- |
-| `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 |
+| Run the first GitHub review | [GitHub quickstart](docs/getting-started/github-quickstart.md) |
+| Confirm the first run worked | [Verify First Review](docs/getting-started/verify-first-review.md) |
+| Improve a working setup | [Next Steps](docs/getting-started/next-steps.md) |
+| Understand the concepts | [Concepts](docs/concepts/README.md) and [Glossary](docs/concepts/glossary.md) |
+| Choose a provider or ACP agent | [Providers](docs/providers/README.md) |
+| Set up GitLab, Azure, or custom CI | [Integrations](docs/integrations/README.md) |
+| Secure secrets and fork PRs | [Secrets and fork PRs](docs/guides/secrets-and-fork-prs.md) |
+| Tune review policy | [Configuration reference](docs/reference/configuration.md) |
+| Consume artifacts or schemas | [Artifacts](docs/reference/artifacts.md) and [findings schema](docs/reference/findings-schema.md) |
+| Debug setup problems | [Troubleshooting](docs/help/troubleshooting.md) |
+| Get quick answers | [FAQ](docs/help/faq.md) |
+| Compare DiffPal to alternatives | [Comparison guide](docs/concepts/comparison.md) |
-DiffPal passes the review task snapshot with base and head revisions. Providers
-inspect the repository diff and supporting code through their available Git and
-filesystem tools, then DiffPal validates the structured findings against the
-changed ranges it collected internally.
+## Project Status
-## MCP Servers
-DiffPal can pass MCP servers through the Norma runtime to providers that support
-them. Declare servers once, then attach them to the provider:
-```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
-```
+DiffPal is under active development. The public docs describe the current
+supported workflow and integration surface.
-Keep MCP credentials in CI secrets. Use envsubst placeholders only for values
-that are guaranteed to exist in that job.
-## Feedback
-Use `feedback` for the normal user-facing shape:
-| Feedback | Behavior |
-| --- | --- |
-| `summary` | Summary plus non-file artifacts such as SARIF, Code Quality, or status. No file-level findings are published. |
-| `review` | Summary plus file-level findings for the platform; non-blocking findings stay visible but do not become merge blockers. The summary does not duplicate file-level finding details. |
-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
-```
-That produces a separate `diffpal-dev` PR review with its own summary and file-level
-comments.
-## Local Debugging
-CI is the main path, but local checks help when wiring a provider:
-```bash
-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 doctor --mode github
-diffpal review local --base origin/main --head HEAD --profile ci
-```
-To inspect the prompt contract without calling any provider:
-```bash
-diffpal debug prompt --base origin/main --head HEAD --profile ci --format text
-```
+## Contributing
-The debug command renders the system prompt, the review task snapshot, and a
-schema-valid mock findings bundle through the normal review validation path.
-It does not require API keys.
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for
+local setup, verification commands, and repository conventions.
-## Documentation
+## License
-- [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)
-- [Azure adapter reference](docs/platform-azure.md)
-- [Release process](docs/release.md)
-- [Contributing](CONTRIBUTING.md)
+DiffPal is released under the [MIT License](LICENSE).

package/bin/diffpal.exe CHANGED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -13,5 +13,5 @@
   "os": [
     "win32"
   ],
-  "version": "0.1.37"
+  "version": "0.1.39"
 }