@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/README.md

@@ -1,25 +1,42 @@
 # PR Review Canvas
 
-Review a GitHub pull request canvas: layers by topic, with grouped diffs, attention points, comments,
-and an optional AI chat. Everything runs locally at **http://localhost:3010**.
+Review a GitHub pull request or GitLab merge request canvas: layers by topic, with grouped diffs,
+attention points, comments, and an optional AI chat. Everything runs locally at **http://localhost:3010**.
 
 ## Quick start: author generates, reviewers review
 
 ### Author side
 
-Each PR author should generate a canvas and attach its zip to the **PR description** before
-requesting review. After the project setup below, run the installed skill in Claude Code or Codex:
+Each PR author generates a canvas before requesting review. The skill shares it automatically
+in a comment on the GitHub PR or GitLab MR. After the project setup below, run the installed skill in Claude Code or Codex:
 
 ```text
 /pr-review-canvas 123
 ```
 
-Replace **123** with your PR number. The skill reads the PR, generates and validates the canvas,
-then returns a local review URL and the exported zip's path. Open the URL to check the canvas.
+Replace **123** with your PR number. The skill reads the PR, generates and validates the canvas, then publishes a compressed canvas
+comment using your `gh` or `glab` login. It returns a local review URL and the comment link.
 
-The skill ends with upload instructions. If you're happy with the produced canvas, edit the PR
-description in GitHub's UI, drag the zip into the editor, wait for the upload to finish, and save.
-Uploading the zip is a manual browser step due to restrictions of GitHub's API.
+If automatic sharing fails (including a canvas too large for one comment), the skill warns you
+and gives you a ZIP path. Drag that ZIP into the PR or MR description, wait for the upload, and
+save. This manual upload is only a fallback.
+
+### Before you open the pull request
+
+To read your own change the way a reviewer will, generate a canvas for the work in your clone:
+
+```text
+/pr-review-canvas branch          # the current branch against the default branch
+/pr-review-canvas uncommitted     # the same, with your working-tree edits and new files on top
+```
+
+Start `pr-review serve` and open **http://localhost:3010/review/branch** or
+**/review/uncommitted**. The two are separate reviews, so generating one leaves the other alone.
+
+Nothing is posted anywhere: local work has no pull request, so the comment and sign-off commands
+stay off. Add `--base <ref>` to compare against another branch. Committing after `branch`, or
+editing a file after `uncommitted`, moves the head: the next time you open the page or press
+refresh, the canvas is marked outdated and the page offers to generate it again.
 
 ### Review side
 
@@ -29,13 +46,16 @@ Start the canvas server from the project you want to review:
 pr-review serve
 ```
 
-Open **http://localhost:3010**, enter a PR number, and leave the terminal running while you
-review. Stop the server with **Ctrl+C**. To use another port, run `pr-review serve --port 3011`.
+Open **http://localhost:3010**, enter a PR number (or follow a link to a local review), and
+leave the terminal running while you review. Stop the server with **Ctrl+C**. To use another port, run `pr-review serve --port 3011`.
 
 ## Install
 
-You need Node.js 22+, npm, Git, and [GitHub CLI](https://cli.github.com).
-Sign in to GitHub with `gh auth login`.
+You need Node.js 22+, npm, Git, and the CLI for your host:
+
+- GitHub: [GitHub CLI](https://cli.github.com). Sign in with `gh auth login`.
+- GitLab: [GitLab CLI (glab)](https://gitlab.com/gitlab-org/cli). Sign in with `glab auth login`.
+  Self-hosted GitLab whose hostname does not contain `gitlab` needs `PR_REVIEW_HOST=gitlab`.
 
 Install the command globally once, for use in any project:
 
@@ -57,10 +77,11 @@ Re-run `pr-review install-skill` after upgrading the CLI to refresh them. It als
 project's `.gitignore`. Restart your coding agent if the skill
 does not appear. Repeat this setup for each project you want to review.
 
-`doctor` checks Git, your GitHub remote, the GitHub CLI and its login, write access to the local
-canvas directory, and whether installed skills match the current package. It prints a JSON report with a result for
-each check and suggested fixes for failures. `doctor --all-checks` also checks that `acpx` runs and
-reports its version. Exit code `0` means all checks passed.
+`doctor` checks Git, your GitHub or GitLab remote, the matching CLI (`gh` or `glab`) and its login,
+write access to the local canvas directory, and whether installed skills match the current package.
+It prints a JSON report with a result for each check and suggested fixes for failures.
+`doctor --all-checks` also checks that `acpx` runs and reports its version. Exit code `0` means all
+checks passed.
 
 `serve` automatically runs the skill check and warns on stderr if a skill is missing, outdated,
 or modified. The warning includes the reinstall command and does not block startup.
@@ -89,22 +110,26 @@ See the [CLI and configuration reference](docs/reference.md) for detailed option
 pr-review export --pr 123
 ```
 
-The command prints the zip's absolute path. Both `export` and `publish` save locally; neither
-uploads an attachment to GitHub.
+The command prints the zip's absolute path. `export` saves locally; `publish` also shares PR/MR
+canvases automatically as compressed comments.
 
 The zip contains `manifest.json` and `review.json`: the PR description, file/hunk metadata,
-and generated review notes. Check these before sharing, since they can contain private
-information. Each reviewer gets source diffs from their own clone; chat history stays local.
+and generated review notes. Publishing shares this information with everyone who can read the PR/MR. Each reviewer gets source diffs from their own clone; chat history stays local.
 
 ### Update an outdated canvas
 
 After pushing new commits, run `/pr-review-canvas 123` again. To rewrite a canvas for the
-same commit, run `/pr-review-canvas 123 --force`. Replace the zip in the PR description.
+same commit, run `/pr-review-canvas 123 --force`. Publishing updates your canvas comment automatically.
 Reviewers click **refresh**.
 
 When the saved canvas describes a different PR head, **Canvas is outdated** appears at
 the top. You can still read the older canvas, with its commit and distance shown; posting
-from that view is disabled. Click **refresh** to check GitHub for changes and a newer zip.
+from that view is disabled. Click **refresh** to check GitHub or GitLab for changes and a newer canvas.
+
+A head whose diff is identical to the canvas's does not outdate it: after **Update branch**
+merged `main` in without touching the changed files, for example, the canvas still applies
+and the page says so. Set `canvas.keepForIdenticalDiff: false` in the project config to treat
+every commit as a new head.
 
 ## Configuration
 
@@ -138,9 +163,9 @@ Customize generation and AI Chat prompts with the `prompts` map in your project'
 
 ```yaml
 prompts:
-  generation-format.md: review-prompts/generation-format.md
-  generation-surfacing.md: review-prompts/generation-surfacing.md
-  chat-seed.md: review-prompts/chat-seed.md
+    generation-format.md: review-prompts/generation-format.md
+    generation-surfacing.md: review-prompts/generation-surfacing.md
+    chat-seed.md: review-prompts/chat-seed.md
 ```
 
 Copy the installed templates to start editing (for an npm global install):
@@ -161,6 +186,10 @@ Restart the server after changing the config; chat template edits apply to new t
 See the [prompt template reference](docs/reference.md#prompt-templates) for supported keys,
 path rules, validation, and upgrades.
 
+## Website
+
+The [project website](https://vintasoftware.github.io/pr-review-canvas/) introduces the review workflow with a real PR walkthrough. See [website development and publishing](docs/website.md) for local preview commands and the GitHub Pages deployment workflow.
+
 ## Contributing
 
 In a clone of this tool, use pnpm for the shared lockfile and development checks:
@@ -168,11 +197,17 @@ In a clone of this tool, use pnpm for the shared lockfile and development checks
 ```bash
 corepack pnpm --version
 corepack pnpm install --frozen-lockfile
+corepack pnpm hooks:install
 corepack pnpm exec playwright install --with-deps chromium
 corepack pnpm verify
 corepack pnpm start --repo /path/to/your-project
 ```
 
+The pre-commit hook runs `pnpm precommit`: lint, formatting, strict type checks, and tests.
+Any failure blocks the commit. Run `pnpm hooks:install`
+once per clone to enable it. Use `pnpm lint:fix` and `pnpm format` to apply automatic fixes.
+CI runs the same checks through `pnpm verify`, with coverage executing the unit tests once.
+
 Run the full `pnpm verify` before pushing. Keep branch coverage at least 96% when adding or
 changing behavior, leaving a margin above CI's 95% minimum. Cover meaningful failure and boundary
 cases rather than lowering thresholds. Each CI job uploads `coverage-node-<version>` with branch