open-azdo 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# open-azdo
+
+`open-azdo` is a Bun CLI for Azure DevOps pull-request review runs in Azure Pipelines. It reviews the checked-out workspace with OpenCode, posts one managed summary thread plus managed inline finding threads, and stays comment-only in v1.
+
+## Why This Exists
+
+This package is the published-package path for secure PR review automation. Unlike the Marketplace extension reference, v1 intentionally does not:
+
+- edit the repository
+- commit or push changes
+- expose command-triggered execution modes
+- run a long-lived OpenCode server
+- rely on tokenized clone URLs
+
+The CLI consumes the Azure Pipeline checkout workspace directly and uses the built-in `System.AccessToken` for the minimal Azure DevOps REST surface.
+
+## Install And Run
+
+Use Bun 1.3.10 or newer.
+
+```bash
+bunx open-azdo review --model "openai/gpt-5.4"
+```
+
+Required inputs:
+
+- `--model` or `OPEN_AZDO_MODEL`
+- `SYSTEM_ACCESSTOKEN`
+
+Common Azure Pipeline defaults:
+
+- `OPEN_AZDO_WORKSPACE` or `BUILD_SOURCESDIRECTORY`
+- `OPEN_AZDO_COLLECTION_URL` or `SYSTEM_COLLECTIONURI`
+- `OPEN_AZDO_PROJECT` or `SYSTEM_TEAMPROJECT`
+- `OPEN_AZDO_REPOSITORY_ID` or `BUILD_REPOSITORY_ID`
+- `OPEN_AZDO_PULL_REQUEST_ID` or `SYSTEM_PULLREQUEST_PULLREQUESTID`
+
+Optional flags:
+
+- `--workspace <path>`
+- `--organization <name>`
+- `--project <name>`
+- `--repository-id <id>`
+- `--pull-request-id <id>`
+- `--collection-url <url>`
+- `--agent <name>` default `azdo-review`
+- `--prompt-file <path>`
+- `--dry-run`
+- `--json`
+
+Exit behavior:
+
+- successful review runs return `0`, even when findings are posted
+- operational failures return non-zero
+
+## Azure Pipelines
+
+The canonical example is in [examples/azure-pipelines.review.yml](/home/ponbac/dev/open-azdo/examples/azure-pipelines.review.yml).
+
+Key requirements:
+
+- use `checkout: self`
+- set `fetchDepth: 0`
+- keep `persistCredentials: false`
+- enable “Allow scripts to access the OAuth token”
+- grant repository read and pull request thread read/write permissions
+
+Attach the pipeline as a branch build-validation policy. Findings are posted as PR comments by default and do not fail the build.
+
+```yaml
+trigger: none
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - checkout: self
+    clean: true
+    fetchDepth: 0
+    persistCredentials: false
+
+  - bash: |
+      set -euo pipefail
+      curl -fsSL https://github.com/oven-sh/bun/releases/download/bun-v1.3.10/bun-linux-x64.zip -o bun.zip
+      unzip -q bun.zip
+      export PATH="$PWD/bun-linux-x64:$PATH"
+
+      curl -fsSL https://github.com/sst/opencode/releases/download/v1.2.27/opencode-linux-x64.tar.gz -o opencode.tar.gz
+      mkdir -p opencode-bin
+      tar -xzf opencode.tar.gz -C opencode-bin
+      export PATH="$PWD/opencode-bin:$PATH"
+
+      bunx open-azdo review --model "$(OpenCodeModel)"
+    displayName: Review Pull Request
+    env:
+      SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+      OPENAI_API_KEY: $(OpenAIApiKey)
+```
+
+## Development
+
+Reference assets live under `.reference/`, including `t3code` for Effect v4
+service and command-runner patterns. Refresh them with:
+
+```bash
+./scripts/pull-ref-repos.sh
+```
+
+Project checks:
+
+```bash
+bun run check
+bun run build
+```

package/SECURITY.md

@@ -0,0 +1,64 @@
+# Security
+
+## Scope
+
+`open-azdo` is review-only in v1. It reads the checked-out workspace, calls OpenCode in read-only mode, and writes Azure DevOps PR threads. It does not edit files, commit, push, or invoke arbitrary helper scripts for mutations.
+
+## Threat Model
+
+Inputs are treated as untrusted:
+
+- pull-request title and description
+- repository contents
+- generated diffs and file excerpts
+- model output
+
+Primary goals:
+
+- never leak secrets to stdout, stderr, or structured logs
+- avoid broad repository or network mutation paths
+- keep Azure DevOps permissions limited to repository read plus PR thread read/write
+
+## Checkout-First Design
+
+The CLI uses the Azure Pipeline checkout workspace instead of PAT-based clone URLs. This avoids embedding tokens in clone commands or remote URLs and keeps auth scoped to the pipeline-provided `System.AccessToken`.
+
+For correct diff resolution, use:
+
+- `checkout: self`
+- `fetchDepth: 0`
+- `persistCredentials: false`
+
+If required history is missing, `open-azdo` fails with a remediation message instead of guessing.
+
+## Secret Handling
+
+- Azure DevOps auth comes from `SYSTEM_ACCESSTOKEN`
+- secrets are wrapped with Effect `Redacted`
+- log rendering sanitizes token-like fields before output
+- authenticated git URLs are never constructed
+
+## OpenCode Containment
+
+Each review run creates a temporary OpenCode config directory and removes it on exit. The generated `azdo-review` agent is read-only:
+
+- read/search/listing tools allowed
+- edit and write denied
+- web fetch and web search denied
+- bash denied by default, with a narrow allowlist for read-style commands
+
+The CLI uses `opencode run --format json` directly. There is no long-lived server and no fixed local port to secure.
+
+## Azure DevOps Mutations
+
+The only intended write surface is PR thread management:
+
+- one managed summary thread
+- one managed inline thread per finding fingerprint
+- stale managed finding threads marked `fixed`
+
+Comment-post failures are surfaced as operational failures and do not get swallowed.
+
+## Reporting
+
+If you find a security issue, avoid opening a public issue with exploit details. Share a minimal reproduction and impact summary privately through the repository’s preferred disclosure channel.