revdeck 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-12
+
+### Added
+
+- Reactions on platform comments: thread cards in the UI, `revdeck react --note <id> --emoji <name>`,
+  and the `reactions.list` / `reactions.toggle` RPC methods. Existing reactions and the current user's
+  choice are shown for GitLab and GitHub.
+- `revdeck eject`: removes the config, installed skills and command files, the `revdeck` MCP entry and
+  the local cache from a repository. It is preview-only without `--yes` and leaves foreign files and
+  other MCP servers intact.
+- Attachments for comments: the UI **Attach** button and `revdeck attach` upload images and videos
+  through the host daemon. GitLab project uploads return absolute URLs, relative `/uploads/` links are
+  normalized to the platform host during publish, and the sanitizer allows images only from that host.
+  Only raster images and videos with matching extension, MIME and file signature are accepted.
+- Devcontainer support: `revdeck devcontainer --write` mounts the host runtime and state directories,
+  sets `REVDECK_*` variables and marks the container, so revdeck reuses the host daemon and never runs
+  `gh`/`glab` inside. `revdeck doctor` checks the host daemon in this mode; `revdeck daemon start
+  --host` exposes the HTTP UI, and `revdeck eject` removes the generated mounts/env.
+
+### Fixed
+
+- `revdeck init` keeps one canonical skill in `.agents/skills/revdeck` (now including
+  `agents/openai.yaml`) and links `.claude/skills/revdeck` to it instead of copying the procedure files.
+  A copy is used only on platforms without symlink support.
+
+## [0.1.0] - 2026-11-11
+
+First public release.
+
+### Added
+
+- Daemon-first architecture: local daemon over a unix socket, SQLite state, multiple reviews.
+- Providers for GitLab and GitHub via `glab`/`gh`: MR/PR info, unified diff, threads, replies,
+  resolve, reactions, line comments, general comments.
+- Approval-gated, idempotent publishing: preview → plan hash → approve → commit.
+- CLI: `init`, `doctor`, `daemon`, `list`, `open`, `context`, `diff`, `threads`, `summary`,
+  `findings`, `reply`, `notes`, `publish`, `rules`, `checks`, `export`, `import`, `ui`, `mcp`.
+- MCP server with 13 tools, `review-mr` and `close-feedback` prompts.
+- Svelte 5 UI: review queue, summary, threads with autosave, findings triage, virtualized-free diff
+  with line comments, rules, publish dialog, command palette, SSE updates.
+- Configurable per-project rules: path → document/section mapping, auto-discovery, checks.
+- Harness adapters for Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Copilot and DSH (MCP).
+- Bilingual product: Russian and English UI with a switch, localized CLI/MCP/context, and separate
+  Russian/English skill packs selected by `revdeck init --lang`.
+- `output.language: auto | ru | en` for review output, independent of the interface language.
+- English documentation as the canonical set under `docs/`, with Russian translations under `docs/ru/`.
+- Security: token scrubbing, redaction, publish sanitizer, loopback-only UI, one-time launch token,
+  cookie/Origin/Host checks, CSP.
+- Docs: architecture, configuration, protocol, threat model, integrations, ADR.
+- Tests: diff parser, core helpers, providers with recorded responses, service with a fake provider.

package/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to revdeck
+
+Thanks for taking the time to contribute. revdeck is a small, dependency-light project: a review
+procedure, a local daemon, platform providers, an MCP server, a CLI and a Svelte UI.
+
+## Good first issues
+
+- A new `Provider` (Bitbucket, Forgejo, Azure DevOps).
+- A harness adapter (Gemini, Zed, JetBrains, a DSH host command).
+- Native drafts for GitLab/GitHub.
+- English translations of `docs/` and `skills/`.
+- UI: reactions panel, review opening dialog, virtualized diff.
+
+## Setup
+
+```bash
+git clone https://github.com/katrov/revdeck.git
+cd revdeck
+npm ci
+npm run typecheck    # tsc + svelte-check
+npm test
+npm run build
+```
+
+For manual testing, `npm run dev:daemon` starts the daemon from source; `npm run dev:ui` starts Vite.
+The daemon serves the built UI from `dist/ui`, so run `npm run build:ui` before checking the full app.
+
+`glab`/`gh` are optional for development: provider tests use recorded CLI responses. To test against a
+real platform, authenticate the CLI and run `revdeck doctor`.
+
+## Project layout
+
+| Path | Responsibility |
+|---|---|
+| `src/core` | Pure functions: diff parser, config, rules, findings, sanitizer, redaction, exec |
+| `src/providers` | Platform-specific code; the only place that knows GitLab/GitHub JSON |
+| `src/daemon` | SQLite store, review service, approvals, RPC, HTTP/SSE |
+| `src/cli` | Commands and installers |
+| `src/mcp` | MCP tools and prompts |
+| `ui` | Svelte 5 SPA |
+| `skills/revdeck` | Review procedures shipped to user projects |
+
+Rules of thumb:
+
+- Keep `src/core` free of network and platform assumptions.
+- A provider returns normalized types from `src/core/types.ts`; no UI or CLI concerns.
+- Publishing must stay approval-gated: never add a path that posts without an `approval_id`.
+- Untrusted text (comments, diff, MR description) never becomes an instruction or a shell command.
+
+## Adding a provider
+
+1. Implement `Provider` from `src/providers/provider.ts`.
+2. Add a branch to `createProvider`.
+3. Add fixture-based tests in `tests/providers.test.ts` using a fake `Runner`.
+4. Document platform quirks (resolve, drafts, line comments) in `docs/architecture.md`.
+
+## Adding a harness adapter
+
+Add a `SPECS` entry in `src/cli/init.ts` with the MCP config path, command file or `linkSkill` flag, then
+document it in `docs/integrations.md`. The canonical skill is always `.agents/skills/revdeck`; adapters
+link to it instead of copying the procedure files. `init` must never overwrite files it does not own.
+
+## Translations
+
+- UI strings live next to their components: `t('русский', 'English')` in `ui/src/lib/i18n.svelte.ts`'s
+  `t` helper. Keep both languages in the same edit.
+- CLI strings use `tr('русский', 'English')` from `src/core/locale.ts`.
+- The skill has two human-maintained packs: `skills/revdeck/ru/` and `skills/revdeck/en/`. They must
+  keep the same structure and semantics; do not machine-translate the review procedure.
+- Tests that assert message text should pin the locale with `setLocale('ru')` or be language-agnostic.
+- Docs: `docs/` is English and canonical, `docs/ru/` is Russian. Keep headings, commands, code blocks
+  and file paths identical between the two; translate prose only.
+
+## Pull requests
+
+- One logical change per PR; include tests for behavior changes.
+- `npm run typecheck`, `npm test` and `npm run build` must pass.
+- Do not commit secrets, `.env` files, tokens, or generated `dist/` artifacts.
+- UI changes: include a screenshot and check light/dark themes.
+- Commits: imperative mood, short subject, explain the *why* in the body. Conventional Commits
+  prefixes (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`) are welcome but not required.
+- By contributing you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Release (maintainers)
+
+```bash
+npm version minor
+git push --follow-tags
+```
+
+The `release` workflow publishes to npm with provenance and creates a GitHub release. It uses
+[trusted publishing](https://docs.npmjs.com/trusted-publishers): GitHub Actions gets a short-lived
+OIDC token, so no npm token is stored in the repository and provenance is generated automatically.
+
+Requirements, all configured once on npmjs.com (package `revdeck` → Settings → Trusted publishing):
+
+- publisher `katrov/revdeck`, workflow file `release.yml`, environment left empty;
+- "stage only" disabled, so tagged releases publish straight away.
+
+The workflow runs on Node 24 and installs npm >= 11.15 because trusted publishing requires npm
+11.5.1 or newer. If `id-token` is not writable the "Verify OIDC permissions" step fails with a
+clear error; `ENEEDAUTH` from npm means the trusted publisher entry does not match the repo,
+workflow file or environment. The version in `src/version.ts` must match `package.json`.
+`prepublishOnly` re-runs build, typecheck and tests.
+
+## Security
+
+Please do not open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 revdeck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# revdeck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/revdeck.svg)](https://www.npmjs.com/package/revdeck)
+[![CI](https://github.com/katrov/revdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/katrov/revdeck/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/revdeck.svg)](https://nodejs.org)
+
+**Agent-first code review for GitLab and GitHub.**
+
+revdeck gives an agent the review context and the project's own rules, lets it write findings and
+replies, and keeps publishing under human control. It runs as a local daemon with a CLI, an MCP server
+and a web UI. Platform tokens stay on the host.
+
+![revdeck UI](docs/screenshot.png)
+
+[Русская версия](README.ru.md) · [Documentation](docs/README.md) (English and Russian)
+
+## Why
+
+- **Rules, not vibes.** For every changed path revdeck selects the repository documents and the exact
+  sections (`AGENTS.md`, architecture, style guides, ADRs). The agent gets a deterministic, size-limited
+  context instead of generic “review this PR” instructions.
+- **Humans publish.** The agent writes drafts. The UI shows exactly what will be posted; publishing is
+  bound to a hash of the plan and is idempotent. There is no “agent approved its own comment” path.
+- **Tokens never reach the agent.** The daemon calls `glab`/`gh` on the host and scrubs platform tokens
+  from child environments. A sandboxed agent only gets an RPC.
+- **GitLab and GitHub.** One model: MR/PR, threads, diff, resolve, reactions, line comments, attachments.
+- **Many reviews.** The daemon keeps them in SQLite; the UI is a triage queue with keyboard shortcuts.
+- **Any harness.** MCP tools for MCP clients, the same capabilities over CLI, and a skill that carries
+  the review procedure.
+
+## How it works
+
+```
+agent (MCP/CLI) ──unix socket──▶ revdeck daemon ──glab/gh──▶ GitLab / GitHub
+                                      │
+                                SQLite + Svelte UI ◀── human
+```
+
+## Install
+
+Requirements: Node.js ≥ 22.13 (Node 24 LTS recommended — `node:sqlite` is experimental in 22.x), `git`, and an authenticated platform CLI
+(`glab auth login` or `gh auth login`). revdeck never reads or stores their tokens.
+
+```bash
+# one-off
+npx revdeck@latest init
+
+# or install globally for daily use
+npm install -g revdeck
+revdeck init
+```
+
+In a repository:
+
+```bash
+cd /path/to/repo
+revdeck init          # .revdeck.yml, skill for your harnesses, MCP config
+revdeck doctor        # node, glab/gh auth, daemon, adapters
+revdeck open 42       # load an MR/PR
+revdeck ui            # open the local UI
+```
+
+`init` never overwrites an existing config without `--force`, and it merges `.mcp.json` instead of
+replacing it. `revdeck eject` is the inverse: it removes the config, installed skills and command files,
+the `revdeck` MCP entry and the local `.revdeck/` cache, leaving foreign files and other MCP servers
+untouched. It only shows the plan by default; add `--yes` to apply (`--keep-config` keeps
+`.revdeck.yml`). Auto-start on login: `revdeck daemon install` (systemd user unit on Linux, launchd
+plist on macOS). Use a global install for this — an `npx` cache path can be evicted.
+
+## Languages
+
+The product is bilingual (Russian and English), and the two languages are independent:
+
+- **Interface and CLI**: follow `--lang ru|en`, then `REVDECK_LANG`, then the system locale. The UI has
+  a RU/EN switch in the sidebar and remembers your choice.
+- **Review output** (findings, replies, summary): `output.language: auto | ru | en` in `.revdeck.yml`.
+  `auto` follows the language of the MR description and threads, so a Russian team can review an
+  English repo and still get Russian comments (or the other way round).
+- **Skill**: `revdeck init --lang en` installs the English procedure; without the flag init follows
+  `REVDECK_LANG`/the system locale and defaults to English.
+- **Project rules** can be written in any language: revdeck reads UTF-8 documents and matches headings
+  (including Cyrillic) without translation. Rules are quoted as-is.
+
+MCP tool descriptions are English — that is the model-facing layer; prompt text follows
+`REVDECK_LANG`. The daemon reads the language at startup, so restart it after changing the language
+(`revdeck daemon restart`).
+
+Documentation is available in English (`docs/`, canonical) and Russian (`docs/ru/`). English and
+Russian READMEs live in this repository; translation fixes are welcome.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `revdeck init` | config, harness adapters, MCP |
+| `revdeck eject [--yes]` | remove revdeck-owned config, adapters and MCP entry |
+| `revdeck devcontainer [--write]` | mount the host daemon socket/state into a devcontainer |
+| `revdeck doctor` | environment, `glab`/`gh` auth, daemon, adapters |
+| `revdeck list [--remote]` | tracked reviews or open ones from the platform |
+| `revdeck open <N\|URL>` | load a review |
+| `revdeck context <N>` | agent context: rules, files, threads, findings |
+| `revdeck diff <N> [--file]` | files and hunks |
+| `revdeck threads <N>` | discussions |
+| `revdeck findings <N> set --file f.json` | write findings |
+| `revdeck reply <N> --thread <id> --body …` | draft a reply |
+| `revdeck publish <N> [--yes]` | preview or publish after confirmation |
+| `revdeck notes <N> …` | line comments from the human |
+| `revdeck react <N> --note <id> --emoji <name>` | toggle a reaction on a platform comment |
+| `revdeck attach <N> --file <image-or-video>` | upload an attachment and print its markdown link |
+| `revdeck rules [--explain <path>]` | effective rules |
+| `revdeck checks <N> [--run --yes]` | project checks |
+| `revdeck export/import <N>` | legacy file exchange |
+| `revdeck ui [N]` | local web UI |
+| `revdeck daemon <start\|stop\|status\|logs\|install>` | daemon lifecycle |
+| `revdeck mcp` | MCP server over stdio |
+
+Common flags: `--json`, `--root`, `--review`, `--platform`, `--project`, `--host`, `--lang ru|en`.
+
+## Attachments
+
+The UI has an **Attach** button next to reply, finding and line-comment editors; the CLI equivalent is
+`revdeck attach <N> --file shot.png`. The file is uploaded by the daemon on the host, and the editor
+receives a markdown link with an absolute platform URL, so GitLab renders images and videos in the
+original MR. Relative GitLab `/uploads/...` links in existing drafts are rewritten to
+`https://<host>/uploads/...` during the publish preview.
+
+GitLab is supported through project uploads (requires a `glab` with `--form` support). GitHub has no
+public attachment API, so the button is disabled there and a link must be pasted manually. Only raster
+images and videos (PNG, JPEG, GIF, WebP, AVIF, MP4, WebM, OGV, MOV) are accepted; SVG and arbitrary
+files are rejected.
+
+## Devcontainer
+
+The daemon, `glab` and `gh` stay on the host. From the repository root:
+
+```bash
+revdeck devcontainer          # print the mounts and environment
+revdeck devcontainer --write  # merge them into .devcontainer/devcontainer.json
+```
+
+The command mounts the host runtime directory at `/run/revdeck` (socket) and the state directory at
+`/var/lib/revdeck` (read-only `daemon.json`), and sets `REVDECK_RUNTIME_DIR`, `REVDECK_STATE_DIR`,
+`REVDECK_DEV_CONTAINER=1` and `REVDECK_UI_HOST`. After rebuilding the container, start the daemon on
+the host. Inside the container revdeck never starts a local daemon, so `gh`/`glab` are never invoked
+there; if the host socket is missing it fails with a clear `DEVCONTAINER` error. `revdeck doctor` is
+aware of this mode. For the UI from the container, start the host daemon with
+`revdeck daemon start --host 0.0.0.0`.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "revdeck": {
+      "command": "npx",
+      "args": ["-y", "revdeck", "mcp"],
+      "env": { "REVDECK_LANG": "en" }
+    }
+  }
+}
+```
+
+Tools: `revdeck_status`, `revdeck_list`, `revdeck_open`, `revdeck_context`, `revdeck_threads`,
+`revdeck_diff`, `revdeck_rules`, `revdeck_draft_reply`, `revdeck_draft_findings`,
+`revdeck_set_summary`, `revdeck_notes`, `revdeck_publish_preview`, `revdeck_publish`.
+
+Publishing requires an `approval_id` that only a human can create (UI or CLI `--yes`). The MCP tool
+does not create one. Prompts `review-mr` and `close-feedback` are available in clients that support
+MCP prompts.
+
+Harness matrix and slash commands: [docs/integrations.md](docs/integrations.md).
+
+## Rules
+
+`.revdeck.yml` at the repository root:
+
+```yaml
+version: 1
+output:
+  language: auto        # auto | ru | en — язык замечаний и ответов
+provider:
+  type: gitlab          # auto | gitlab | github
+  host: gitlab.example.com
+  project: group/project
+  base: develop
+rules:
+  sources: [AGENTS.md, CONTRIBUTING.md]
+  map:
+    - match: "src/**"
+      docs: [docs/Architecture.md, "docs/Styleguide.md#Базовый стиль"]
+    - match: "src/state/**"
+      docs: [docs/StateManagement.md]
+  ignore: ["**/generated/**"]
+checks:
+  - id: lint
+    argv: [npm, run, lint]
+    when: ["src/**"]
+publish:
+  requireApproval: true
+  maxComments: 50
+```
+
+Document selectors: `docs/File.md`, `docs/File.md#Heading`, `docs/File.md#L10-L25`. Without a config,
+revdeck discovers `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` and `docs/*` and warns when nothing is
+found. Full schema: [docs/configuration.md](docs/configuration.md).
+
+## Security
+
+- The daemon listens on loopback and a unix socket (0600). The UI uses a one-time launch token, an
+  `HttpOnly`/`SameSite=Strict` cookie, `Host`/`Origin` checks and CSP.
+- `glab`/`gh` run without a shell, with `cwd` outside the working copy and a scrubbed environment;
+  secrets are redacted from logs and errors.
+- Comments are checked for GitLab quick actions, HTML, hidden/bidi characters, mass mentions and
+  external images (only uploads from the platform host are allowed).
+- Review text is untrusted data; agent instructions say so explicitly.
+
+Details: [docs/threat-model.md](docs/threat-model.md). The guarantee is: the token does not cross the
+sandbox boundary and is not returned over RPC. If a process can read the user's home directory, it can
+read the CLI configuration — isolate the agent.
+
+## Architecture
+
+| Path | Contents |
+|---|---|
+| `src/core` | models, diff parser, rules compiler, findings, sanitizer, safe exec |
+| `src/providers` | GitLab and GitHub via `glab`/`gh`, normalized |
+| `src/daemon` | SQLite, service, unix-socket RPC, HTTP/SSE, approvals |
+| `src/cli` | commands, `init`, `doctor`, export/import |
+| `src/mcp` | MCP server over stdio |
+| `ui` | Svelte 5 + Vite |
+| `skills/revdeck` | review procedures (SKILL, Review, Feedback, Criteria, Rules, Sources, `agents/openai.yaml`) |
+
+More: [docs/architecture.md](docs/architecture.md), [docs/protocol.md](docs/protocol.md),
+[ADR-0001](docs/adr/0001-daemon-first.md).
+
+## Development
+
+```bash
+npm ci
+npm run typecheck     # tsc + svelte-check
+npm test              # vitest
+npm run build         # dist/cli.js, dist/daemon.js, dist/mcp.js, dist/ui
+npm run dev:daemon    # daemon from source
+npm run dev:ui        # Vite dev server (the daemon serves dist/ui)
+```
+
+Provider tests use recorded CLI responses and need no network. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Status
+
+- Publishing uses regular comments; native drafts (GitLab draft notes, GitHub pending review) are not
+  used yet, though the provider interface is ready.
+- Project checks are planned by the agent; running them requires `revdeck checks --run --yes`.
+- The UI does not open a new review by number; use the CLI and the review appears in the list.
+- Thread resolution is in the thread card; reactions are available on thread notes in the UI and through
+  `revdeck react`.
+- GitHub has no public attachment API: the Attach button is disabled there; uploads work in GitLab.
+- Auto-start is supported on Linux and macOS; on Windows run the daemon manually.
+
+## License
+
+[MIT](LICENSE)