release: v0.6.1 — scan JSON parse, review exit code, macOS Gatekeeper, install docs

.github/workflows/deploy-website.yml

@@ -52,4 +52,4 @@ jobs:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           preCommands: npx wrangler pages project create cora-cli --production-branch=main || true
-          command: pages deploy docs/.vitepress/dist/ --project-name=cora-cli --commit-dirty=true --branch=main
+          command: pages deploy docs/.vitepress/dist/ --project-name=cora-cli --commit-dirty=true

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-06-17
+
+### Fixed — Scan
+
+- **`cora scan` no longer aborts on non-JSON LLM responses (#316)**
+  - Detect non-JSON responses early (provider error pages, rate-limit bodies, empty responses, prose wrappers) and surface the raw response prefix (first 512 bytes) in the error message so users can diagnose the cause.
+  - Per-batch parse failures are now **non-fatal by default**: the failing batch is skipped with a `warn`-level log and a stderr warning listing the affected files, and the scan continues with the remaining batches. Set `--no-continue-on-batch-error` to restore the old abort behavior.
+  - Added `--batch-files <N>` flag (default: 20) to control the maximum number of files per LLM batch — lower it to work around provider token limits or rate-limit errors on large scans.
+  - Truncated-JSON and general parse errors now include the raw response prefix for easier debugging without `--verbose`.
+
+### Fixed — Review
+
+- **`cora review` no longer exits 2 when severity filtering removes all blocking findings (#312)**
+  - Recompute `should_block` against the **filtered** issue list (after `--severity` filtering) so the exit code matches the SARIF/pretty output the user sees.
+  - Extracted exit-code logic into `compute_exit_code()` helper (pure function) with 8 unit tests covering gate pass/fail, CI mode, and hook `block` vs non-`block` modes.
+  - Applies to both the single-chunk and auto-chunked (`--auto-chunk`) review paths.
+
+### Fixed — Install (macOS)
+
+- **macOS installer now strips Gatekeeper quarantine attributes (#313)**
+  - Prebuilt macOS binaries (`aarch64-apple-darwin`) are not Apple-notarized. When downloaded directly, macOS attaches `com.apple.quarantine` / `com.apple.provenance` xattrs and kills the binary with `Killed: 9` on first launch.
+  - `install.sh` now runs `xattr -dr` for both attributes on the installed binary on macOS (best-effort, non-fatal).
+  - Added a prominent `<details>` block in the README install section explaining the symptom, the manual `xattr` workaround for users who download the binary directly, and the `cargo` / Homebrew alternatives.
+
+### Changed — Docs
+
+- **Install section now warns about multiple distribution channels (#314)**
+  - Recommends a single install method per platform and lists the supported channels (installer script, `cargo`, pre-built binaries).
+  - Adds a `which -a cora && cora --version` check snippet and guidance for removing stale copies when more than one `cora` is on `PATH` (e.g. `~/.local/bin` vs `~/.cargo/bin` vs npm global).
+  - Cross-links the original issue for background.
+
 ## [0.6.0] - 2026-06-14
 
 ### Added — Code Intelligence
@@ -502,7 +533,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cross-platform** — Linux (x86_64, ARM64), macOS (Apple Silicon), Windows (x86_64)
 - **MIT License** — fully open source
 
-[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...develop
+[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.6.1...develop
+[0.6.1]: https://github.com/codecoradev/cora-cli/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/codecoradev/cora-cli/compare/v0.4.6...v0.5.0
 [0.4.6]: https://github.com/codecoradev/cora-cli/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/codecoradev/cora-cli/compare/v0.4.4...v0.4.5

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cora-cli"
-version = "0.6.0"
+version = "0.6.1"
 edition = "2024"
 description = "CLI-first AI code review — BYOK, diff/scan/branch, pre-commit hooks"
 license = "MIT"

README.md

@@ -36,17 +36,54 @@
 
 ### Install
 
+Pick **one** install method — mixing channels can leave stale binaries on your `PATH`.
+
+| Method | When to use |
+|---|---|
+| **`curl … install.sh`** (recommended) | Quick standalone install; fetches the latest GitHub release binary |
+| **`cargo install --git …`** | You already have a Rust toolchain; builds from source |
+| **Pre-built binaries** | Manual download from [Releases](https://github.com/codecoradev/cora-cli/releases) |
+
 ```bash
-# Cora only (standalone)
+# Recommended: Cora only (standalone)
 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install.sh | sh
 
 # Or install both Cora + Uteke (code review with memory)
 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install-bundle.sh | sh
+
+# Or build from source with cargo
+cargo install --git https://github.com/codecoradev/cora-cli
+```
+
+> Pin a version: `CORA_VERSION=v0.6.1 curl -fsSL ... | sh`
+
+**Verify which `cora` you're running** — `which -a cora` will reveal stale copies from other channels:
+
+```bash
+which -a cora            # list every `cora` on your PATH (one entry = healthy)
+cora --version           # should match the latest release
 ```
 
-> Pin a version: `CORA_VERSION=v0.6.0 curl -fsSL ... | sh`  
-> Or: `cargo install --git https://github.com/codecoradev/cora-cli`  
-> Pre-built binaries: [GitHub Releases](https://github.com/codecoradev/cora-cli/releases)
+If `which -a cora` shows more than one path (e.g. `~/.local/bin/cora` and `~/.cargo/bin/cora`), remove the one you don't want or reorder your `PATH`. See [Issue #314](https://github.com/codecoradev/cora-cli/issues/314) for background.
+
+<details>
+<summary><b>macOS note — binary killed on launch (<code>Killed: 9</code>)?</b></summary>
+
+The prebuilt `aarch64-apple-darwin` binary is not Apple-notarized. On macOS, downloaded
+binaries may be tagged with `com.apple.quarantine` / `com.apple.provenance` and killed by
+Gatekeeper with **no error message**.
+
+The `install.sh` installer strips these attributes automatically. If you downloaded the
+binary manually (e.g. `gh release download`), strip them yourself:
+
+```bash
+xattr -dr com.apple.quarantine /path/to/cora
+xattr -dr com.apple.provenance /path/to/cora
+```
+
+Or install via `cargo` / Homebrew to sidestep Gatekeeper entirely.
+
+</details>
 
 ### Authenticate
 

docs/changelog.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-06-17
+
+### Fixed — Scan
+
+- **`cora scan` no longer aborts on non-JSON LLM responses (#316)**
+  - Detect non-JSON responses early (provider error pages, rate-limit bodies, empty responses, prose wrappers) and surface the raw response prefix (first 512 bytes) in the error message so users can diagnose the cause.
+  - Per-batch parse failures are now **non-fatal by default**: the failing batch is skipped with a `warn`-level log and a stderr warning listing the affected files, and the scan continues with the remaining batches. Set `--no-continue-on-batch-error` to restore the old abort behavior.
+  - Added `--batch-files <N>` flag (default: 20) to control the maximum number of files per LLM batch — lower it to work around provider token limits or rate-limit errors on large scans.
+  - Truncated-JSON and general parse errors now include the raw response prefix for easier debugging without `--verbose`.
+
+### Fixed — Review
+
+- **`cora review` no longer exits 2 when severity filtering removes all blocking findings (#312)**
+  - Recompute `should_block` against the **filtered** issue list (after `--severity` filtering) so the exit code matches the SARIF/pretty output the user sees.
+  - Extracted exit-code logic into `compute_exit_code()` helper (pure function) with 8 unit tests covering gate pass/fail, CI mode, and hook `block` vs non-`block` modes.
+  - Applies to both the single-chunk and auto-chunked (`--auto-chunk`) review paths.
+
+### Fixed — Install (macOS)
+
+- **macOS installer now strips Gatekeeper quarantine attributes (#313)**
+  - Prebuilt macOS binaries (`aarch64-apple-darwin`) are not Apple-notarized. When downloaded directly, macOS attaches `com.apple.quarantine` / `com.apple.provenance` xattrs and kills the binary with `Killed: 9` on first launch.
+  - `install.sh` now runs `xattr -dr` for both attributes on the installed binary on macOS (best-effort, non-fatal).
+  - Added a prominent `<details>` block in the README install section explaining the symptom, the manual `xattr` workaround for users who download the binary directly, and the `cargo` / Homebrew alternatives.
+
+### Changed — Docs
+
+- **Install section now warns about multiple distribution channels (#314)**
+  - Recommends a single install method per platform and lists the supported channels (installer script, `cargo`, pre-built binaries).
+  - Adds a `which -a cora && cora --version` check snippet and guidance for removing stale copies when more than one `cora` is on `PATH` (e.g. `~/.local/bin` vs `~/.cargo/bin` vs npm global).
+  - Cross-links the original issue for background.
+
 ## [0.6.0] - 2026-06-14
 
 ### Added — Code Intelligence
@@ -502,7 +533,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cross-platform** — Linux (x86_64, ARM64), macOS (Apple Silicon), Windows (x86_64)
 - **MIT License** — fully open source
 
-[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...develop
+[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.6.1...develop
+[0.6.1]: https://github.com/codecoradev/cora-cli/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/codecoradev/cora-cli/compare/v0.4.6...v0.5.0
 [0.4.6]: https://github.com/codecoradev/cora-cli/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/codecoradev/cora-cli/compare/v0.4.4...v0.4.5

docs/cli-reference.md

@@ -41,6 +41,8 @@ Complete command reference for the cora CLI.
 | `cora review --upload` | Review and upload SARIF to GitHub Code Scanning |
 | `cora scan` `<path>` | Scan files for issues |
 | `cora scan .` `[--incremental]` | Scan only changed files |
+| `cora scan .` `[--batch-files N]` | Max files per LLM batch (default: 20). Lower to work around provider token limits |
+| `cora scan .` `[--no-continue-on-batch-error]` | Abort the scan when a batch fails to parse (default: skip and continue) |
 | `cora config show` | Show resolved configuration |
 | `cora config show --global` | Show global config (`~/.cora/config.yaml`) |
 | `cora config show --project` | Show project config (`.cora.yaml`) |

docs/installation.md

@@ -21,7 +21,7 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
 Pin a specific version:
 
 ```bash
-$ CORA_VERSION=v0.6.0 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install.sh | sh
+$ CORA_VERSION=v0.6.1 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install.sh | sh
 ```
 
 ## Install via Cargo
@@ -85,13 +85,42 @@ Confirm cora is installed correctly:
 
 ```bash
 $ cora --version
-cora 0.x.x
+cora 0.6.1
 
 $ cora auth status
 Provider: openai
 API key: configured
 ```
 
+### Check for stale copies on PATH
+
+cora is distributed through multiple channels (installer script, `cargo`, pre-built binaries). If you have more than one installed, `which cora` resolves to whichever appears first in `$PATH` — which may silently be a stale version.
+
+```bash
+# List every `cora` on your PATH (one entry = healthy)
+$ which -a cora
+/Users/you/.local/bin/cora
+
+# Should match the latest release
+$ cora --version
+cora 0.6.1
+```
+
+If `which -a cora` shows more than one path (e.g. `~/.local/bin/cora` and `~/.cargo/bin/cora`), remove the one you don't want or reorder your `PATH`. See [Issue #314](https://github.com/codecoradev/cora-cli/issues/314) for background.
+
+## macOS: `Killed: 9` on launch?
+
+Prebuilt macOS binaries (`aarch64-apple-darwin`) are not Apple-notarized. When downloaded directly (via browser, `curl`, or `gh release download`), macOS attaches `com.apple.quarantine` / `com.apple.provenance` extended attributes and kills the binary on first launch with `Killed: 9` and **no error message**.
+
+The `install.sh` installer strips these attributes automatically. If you downloaded the binary manually, strip them yourself:
+
+```bash
+$ xattr -dr com.apple.quarantine /path/to/cora
+$ xattr -dr com.apple.provenance /path/to/cora
+```
+
+Or install via `cargo` / Homebrew to sidestep Gatekeeper entirely.
+
 ## Updating
 
 To update cora to the latest version:

docs/public/_redirects

@@ -0,0 +1 @@
+/docs/cora/*  /:splat  200

docs/usage.md

@@ -288,5 +288,6 @@ Trend indicators: ▼ improving (fewer findings), ► stable, ▲ worsening (mor
 - Use `cora review` with no flags for the fastest pre-commit feedback
 - Combine `--format json` with `--base main` in CI pipelines
 - Use `cora scan . --incremental` for large codebases — only changed files are analyzed
+- For large scans that hit provider token limits or rate-limits, lower the batch size with `--batch-files 10` (default: 20). Failed batches are skipped by default — pass `--no-continue-on-batch-error` to abort instead
 - Use `--quiet` for minimal output and `--severity` to filter by severity level
 - Use `cora auth login` to store API keys securely instead of environment variables

install.sh

@@ -141,6 +141,16 @@ install() {
 
     chmod +x "${INSTALL_DIR}/${BINARY_NAME}"
 
+    # macOS Gatekeeper workaround (#313): strip quarantine/provenance xattrs
+    # that the browser/curl attaches to downloaded binaries. Without this,
+    # macOS kills the unsigned binary with `Killed: 9` and no error message.
+    if [ "$OS" = "darwin" ] && command -v xattr >/dev/null 2>&1; then
+        # Best-effort — failures here are non-fatal (binary may already be clean).
+        xattr -dr com.apple.quarantine "${INSTALL_DIR}/${BINARY_NAME}" 2>/dev/null || true
+        xattr -dr com.apple.provenance "${INSTALL_DIR}/${BINARY_NAME}" 2>/dev/null || true
+        info "Stripped macOS quarantine attributes (Gatekeeper workaround)"
+    fi
+
     # Cleanup
     rm -rf "$TEMP_DIR"