@a9n-shoji/rvw 0.1.0

package/migrations/008_walkthrough_line_comments.sql

@@ -0,0 +1,62 @@
+CREATE TABLE comment_targets_v4 (
+  comment_id TEXT PRIMARY KEY REFERENCES comments(id) ON DELETE CASCADE,
+  target_kind TEXT NOT NULL CHECK(target_kind IN ('pull_request', 'document', 'walkthrough')),
+  document_kind TEXT CHECK(document_kind IN ('pull_request_markdown', 'repository_file')),
+  source_oid TEXT,
+  file_path TEXT,
+  source_document_hash TEXT,
+  quoted_text TEXT,
+  walkthrough_id TEXT REFERENCES walkthroughs(id),
+  start_line INTEGER,
+  end_line INTEGER,
+  CHECK(start_line IS NULL OR start_line >= 1),
+  CHECK(end_line IS NULL OR end_line >= start_line),
+  CHECK(
+    (target_kind = 'pull_request' AND document_kind IS NULL AND source_oid IS NULL AND file_path IS NULL AND source_document_hash IS NULL AND quoted_text IS NULL AND walkthrough_id IS NULL AND start_line IS NULL AND end_line IS NULL)
+    OR
+    (target_kind = 'document' AND document_kind = 'pull_request_markdown' AND source_oid IS NULL AND file_path IS NULL AND source_document_hash IS NOT NULL AND walkthrough_id IS NULL)
+    OR
+    (target_kind = 'document' AND document_kind = 'repository_file' AND source_oid IS NOT NULL AND file_path IS NOT NULL AND source_document_hash IS NULL AND quoted_text IS NULL AND walkthrough_id IS NULL)
+    OR
+    (
+      target_kind = 'walkthrough' AND document_kind IS NULL AND source_oid IS NULL AND file_path IS NULL AND walkthrough_id IS NOT NULL
+      AND (
+        (start_line IS NULL AND end_line IS NULL AND quoted_text IS NULL)
+        OR
+        (start_line IS NOT NULL AND end_line IS NOT NULL AND source_document_hash IS NOT NULL AND quoted_text IS NOT NULL)
+      )
+    )
+  ),
+  CHECK((start_line IS NULL AND end_line IS NULL) OR (start_line IS NOT NULL AND end_line IS NOT NULL))
+);
+
+INSERT INTO comment_targets_v4(
+  comment_id,
+  target_kind,
+  document_kind,
+  source_oid,
+  file_path,
+  source_document_hash,
+  quoted_text,
+  walkthrough_id,
+  start_line,
+  end_line
+)
+SELECT
+  comment_id,
+  target_kind,
+  document_kind,
+  source_oid,
+  file_path,
+  source_document_hash,
+  quoted_text,
+  walkthrough_id,
+  start_line,
+  end_line
+FROM comment_targets;
+
+DROP TABLE comment_targets;
+ALTER TABLE comment_targets_v4 RENAME TO comment_targets;
+
+CREATE INDEX comment_targets_document ON comment_targets(document_kind, source_oid, file_path);
+CREATE INDEX comment_targets_walkthrough ON comment_targets(walkthrough_id);

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@a9n-shoji/rvw",
+  "version": "0.1.0",
+  "description": "Human-centered repository viewer for understanding and refining GitHub pull request changes",
+  "keywords": [
+    "code-review",
+    "developer-tools",
+    "github",
+    "local-first",
+    "pull-request"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/a9n-shoji/rvw#readme",
+  "bugs": {
+    "url": "https://github.com/a9n-shoji/rvw/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a9n-shoji/rvw.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "bin": {
+    "rvw": "dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "skills",
+    "CHANGELOG.md",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.15.0",
+    "pnpm": "11.21.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@hono/node-server": "^2.1.0",
+    "@pierre/diffs": "1.3.5",
+    "@pierre/vscode-icons": "^0.0.9",
+    "@playwright/test": "^1.62.1",
+    "@tanstack/react-query": "^5.101.4",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "commander": "^15.0.0",
+    "diff": "9.0.0",
+    "env-paths": "^4.0.0",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.8.1",
+    "fuzzysort": "^3.1.0",
+    "globals": "^17.9.0",
+    "hono": "^4.13.1",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mermaid": "^11.16.1",
+    "npm": "11.19.0",
+    "open": "^11.0.0",
+    "prettier": "^3.9.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-markdown": "^10.1.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "tsx": "^4.23.11",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.66.0",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "dev": "tsx src/cli/main.ts open --no-open",
+    "check": "tsc --noEmit && eslint . && prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "node scripts/build.mjs && playwright test",
+    "test:package": "node scripts/package-smoke.mjs",
+    "build": "node scripts/build.mjs",
+    "start": "node dist/cli.mjs",
+    "release:verify": "tsx scripts/verify-release.ts",
+    "format": "prettier --write ."
+  }
+}

package/skills/rvw/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rvw
+description: Inspect, address, reply to, resolve, reopen, and synchronize rvw review comments through the local rvw CLI. Use when a request contains rvw://comment references, asks to handle feedback recorded in rvw, or asks to synchronize rvw after pushed changes. Do not use this Skill to publish implementation walkthroughs; use rvw-walkthrough for that task.
+---
+
+# rvw review comments
+
+Use only the `rvw` CLI protocol to access rvw state. Never read or edit the SQLite database directly. Require a local Agent with access to the saved repository. A running rvw viewer can provide database access through its user-only Unix socket; require direct rvw data-directory access only when that route is unavailable. Do not guess comment contents when required access is unavailable.
+
+## Preflight
+
+1. Run `rvw protocol --json` and parse stdout as JSON.
+2. Require `protocolVersion` 2, `agent.transport`, and every task capability needed for the task.
+3. Run `rvw agent status --json`. Read `socketPath`, `connectionResult`, `selectedDatabasePath`, `selectedTransport`, and `fallbackReason`. If `selectedTransport` is `unavailable`, stop and report the diagnostic; an explicitly configured `RVW_AGENT_SOCKET_PATH` never falls back to direct database access. Otherwise use the reported transport without overriding it.
+4. Prefer the CLI's transparent Unix-socket route when a normally launched rvw viewer is running.
+   Explain the exact local permission needed only if both the socket route and direct CLI access are
+   unavailable. `RVW_DATABASE_PATH` selects an explicitly managed database path; the CLI uses a
+   running viewer only when it reports that same database.
+
+## Read comments
+
+When the user asks for unresolved feedback without supplying individual comment references, run:
+
+```bash
+rvw comment list <PULL_REQUEST> --state unresolved --limit 50 --offset 0 --json
+```
+
+The default state is `unresolved`; use `--state resolved` or `--state all` only when the request needs
+those threads. Require the `comment.list` capability before discovery. Continue with
+`--offset <nextOffset>` while the page has `hasMore: true`; never assume the first page is complete.
+Each item contains a bounded root-post preview, post count, target summary, and service-derived
+`latestPlacement`, but omits replies, exact target evidence, and source excerpts. Run `comment get`
+for every listed thread that you will inspect or address; never act from the preview alone. Collect
+the URIs from every page before replying, resolving, or reopening because those writes can reorder or
+remove entries from later offset pages.
+
+Run the following for every supplied `rvw://comment/<uuid>` reference:
+
+```bash
+rvw comment get <COMMENT_URI> --json
+```
+
+Use `pullRequest.localRepositoryPath` as the repository to inspect or modify. Read the latest PR title,
+base/head branch names and OIDs, the exact target, all posts, `createdHeadOid`, `latestHeadOid`,
+`latestPlacement`, and `exactSource` before deciding what the comment requests. The default response
+omits `pullRequest.body`. Group the fetched comments by Pull Request. If any comment in a group targets
+the PR or PR Markdown, or any thread in that group cannot be understood without PR-level intent, rerun
+`comment get` for exactly one representative URI in that group with `--include-pr-body`. Reuse that
+latest successfully synchronized body for every comment from the same Pull Request; never request the
+same PR body once per comment. When supplied references span multiple Pull Requests, fetch the body at
+most once for each group that needs it. `latestPlacement` is rvw's authoritative derived placement at
+the latest head; never infer Outdated by comparing OIDs.
+
+When the task needs to distinguish the cached snapshot from current GitHub state, use
+`rvw comment get <COMMENT_URI> --live --json`. Read `githubState.staleAgainstGitHub` and live metadata;
+this lookup is read-only and does not make the cached PR current. Without `--live`, null live fields mean
+GitHub was not checked.
+
+- For a repository-file target, inspect its recorded source OID and path even when it is Outdated.
+  `exactSource.excerpt` contains the selected lines with bounded context when available, and its
+  truncation fields say whether more of the exact document must be read from the repository. Treat the
+  excerpt as an entry point, not a substitute for inspecting relevant surrounding code.
+  `exactSource.availability` is exactly `available`, `binary`, `too-large`, or `missing`; only
+  `available` has a non-null excerpt.
+- For a PR-Markdown target, combine its quoted text with the latest `Pull Request.md`; request that
+  body through the group's single representative `comment get <COMMENT_URI> --include-pr-body --json`
+  call if it has not already been loaded. rvw does not retain the complete historical PR body; never
+  treat `createdHeadOid` as a PR-body revision.
+- For a Walkthrough target, read the complete current `walkthrough` object returned by `comment get`, including its body, source OID, diagram bindings, and code references. Whole-document comments remain attached when that Walkthrough is updated in place.
+
+## Address comments
+
+1. Confirm the authorized scope from the prompt and comment thread.
+2. Inspect the current worktree and relevant surrounding code. Preserve unrelated user changes.
+3. Implement only authorized changes and run proportionate tests.
+4. Reply with concrete findings when no code change is needed.
+5. Resolve only when the user requested resolution or the thread is demonstrably satisfied. A reply alone does not resolve a thread.
+
+When feedback asks to improve the explanation rather than the code, use the `rvw-walkthrough` Skill to update the same Walkthrough URI after understanding the full thread. Do not publish a duplicate as an implicit version. Return to this Skill for any authorized reply or resolution.
+
+Every `--stdin` command reads until EOF before parsing JSON. Supply the complete object and close stdin in the same non-interactive invocation. Prefer an execution API that accepts stdin and closes it after writing; in a shell, use a quoted heredoc. Never start the command in an interactive PTY and send only JSON plus a newline because a newline is not EOF.
+
+To add a standalone reply, use one closed-stdin invocation:
+
+```bash
+rvw comment reply '<COMMENT_URI>' --stdin --json <<'RVW_JSON'
+{
+  "body": "Investigation result or completed change",
+  "authorLabel": "Agent name",
+  "relatedCommitOid": null
+}
+RVW_JSON
+```
+
+Set `authorLabel` to an accurate current Agent name when known; otherwise omit it. This command is not idempotent. After an uncertain failure, re-read the comment before retrying to avoid a duplicate reply.
+
+A resolved thread accepts replies, and replying does not reopen it. Likewise, a `pr sync` reply leaves
+the current state unchanged unless its update has `resolve: true`. Use `comment reopen` as a separate,
+explicit state change when the user requests reopening; never assume that a reply changed the state.
+
+Use `rvw comment resolve <COMMENT_URI> --json` and `rvw comment reopen <COMMENT_URI> --json` for explicit state changes.
+
+## Synchronize pushed changes
+
+Synchronize only GitHub-visible state. Complete authorized code changes, tests, commit, push, and any required PR title or body update first. Never represent uncommitted or unpushed local changes as synchronized state.
+
+Pass one JSON object and close stdin in the same invocation:
+
+```bash
+rvw pr sync --stdin --json <<'RVW_JSON'
+{
+  "pullRequest": "https://github.com/owner/repo/pull/123",
+  "commentUpdates": [
+    {
+      "commentRef": "rvw://comment/uuid",
+      "reply": "Change included in the pushed commit",
+      "resolve": false
+    }
+  ]
+}
+RVW_JSON
+```
+
+Prefer this atomic path when the GitHub refresh and comment updates belong to the same operation. Successful replies are linked to the synchronized head commit. The command is not idempotent when it adds replies; re-read affected comments before retrying an uncertain result.
+
+If the saved checkout is dirty but a clean worktree in the same Git common directory exists, pass
+`--repository <PATH>`. Inspect every reported dirty entry before deciding whether untracked files are
+irrelevant; only then may you explicitly pass `--allow-untracked`. Never use that option to ignore
+tracked changes. A clean local PR branch that is merely behind GitHub is acceptable and rvw will not
+move its checkout. To change only the saved worktree path without starting a viewer, use
+`rvw pr attach <PULL_REQUEST> --repository <PATH> --json`.
+
+If rvw reports `LOCAL_STATE_INCONSISTENT`, report its reset guidance and deletion counts. Never run `rvw pr reset ... --yes` without explicit authorization because it permanently removes local comments, Walkthroughs, and retained rvw refs.

package/skills/rvw/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "rvw"
+  short_description: "Inspect and address review comments through rvw"
+  default_prompt: "Use $rvw to inspect and address the supplied rvw comment references."

package/skills/rvw-walkthrough/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rvw-walkthrough
+description: Read, publish, improve in place, or explicitly delete a commit-fixed Markdown explanation with exact code references and optional Mermaid bindings through the local rvw CLI. Use when the user asks to create, present, publish, revise, update, or remove an implementation, surrounding-code, flow, or architecture walkthrough in rvw. Do not use this Skill for rvw comment handling or PR synchronization.
+---
+
+# rvw Walkthrough management
+
+Turn the explanation appropriate to the current request and repository into a verifiable rvw artifact. Leave the document's organization, emphasis, granularity, and use of diagrams to the current session; do not impose fixed headings or a narrative template.
+
+Use only the `rvw` CLI protocol. Never access the SQLite database directly or control a viewer through browser automation.
+
+## Preflight
+
+1. Run `rvw protocol --json` and parse stdout as JSON.
+2. Require `protocolVersion` 2, `agent.transport`, and the `walkthrough.read` capability plus every publish, update, or delete capability needed for the task.
+3. Run `rvw agent status --json`. Read `socketPath`, `connectionResult`, `selectedDatabasePath`, `selectedTransport`, and `fallbackReason`. If `selectedTransport` is `unavailable`, stop and report the diagnostic; an explicitly configured `RVW_AGENT_SOCKET_PATH` never falls back to direct database access. Otherwise use the reported transport without overriding it.
+4. Require local access to the saved repository. When a normally launched rvw viewer is running, the
+   CLI can route database reads and writes through its user-only Unix socket; otherwise direct rvw data
+   access is required. `RVW_DATABASE_PATH` selects an explicitly managed database; the CLI uses a
+   running viewer only when it reports that same database.
+
+## Read the current artifact
+
+For an existing `rvw://walkthrough/<uuid>` reference, run:
+
+```bash
+rvw walkthrough get <WALKTHROUGH_URI> --json
+```
+
+Read the complete current body, source OID, diagram bindings, references, and Pull Request repository location before revising or deleting it. Walkthroughs have one current value and no local revision history.
+
+## Prepare the artifact
+
+1. Inspect the user's requested scope and the relevant committed repository state.
+2. Choose one exact commit containing every referenced path. Do not publish an explanation of uncommitted code.
+3. Compose the explanation in the structure best suited to the current task. Make material boundaries and uncertainty explicit.
+4. Link important code claims with Markdown URLs of the form `rvw-ref:<referenceId>`.
+5. Define every reference with a repository-relative path and, when useful, an inclusive line range at the chosen `sourceOid`. Prefer the smallest meaningful multi-line range that lets the reader verify a code block or flow; include the signature and relevant body instead of pointing only at its first line. Use a single-line range only for a genuinely line-local claim such as one constant or declaration. Omit both `startLine` and `endLine` when the claim concerns the file as a whole. Keep IDs unique and stable within the publication.
+6. Add Mermaid only when it helps the explanation. Bind only elements that should open code. rvw renders Mermaid-supported diagram types, while interactive binding is currently guaranteed for flowchart nodes and class-diagram classes.
+7. Ensure every supplied reference is used by at least one Markdown `rvw-ref:` link or a Mermaid binding whose key is an actual flowchart node or classDiagram class in the body, and ensure every link and binding names a supplied reference. Never invent a binding key merely to mark a reference as used. For a line reference, supply both `startLine` and `endLine`; for a file reference, omit both. Let the CLI reject invalid commits, paths, ranges, IDs, unused references, or bindings; never silently omit a failed reference.
+
+## Send JSON without interactive input
+
+Every `--stdin` command reads until EOF before parsing JSON. Supply the complete object and close stdin in the same non-interactive invocation. Prefer an execution API that accepts stdin and closes it after writing; in a shell, use a quoted heredoc as shown below. Never start the command in an interactive PTY and send only JSON plus a newline: a newline is not EOF, so the command will keep waiting.
+
+## Publish
+
+Pass exactly one JSON object and close stdin. This shell form closes it at the heredoc delimiter:
+
+```bash
+rvw walkthrough publish --stdin --json <<'RVW_JSON'
+{
+  "pullRequest": "https://github.com/owner/repo/pull/123",
+  "sourceOid": "0123456789abcdef0123456789abcdef01234567",
+  "title": "Request flow",
+  "body": "Start at [the handler](rvw-ref:handler), then inspect the [composition root](rvw-ref:composition).",
+  "diagramBindings": { "Handler": "handler" },
+  "references": [
+    {
+      "id": "handler",
+      "label": "RequestHandler.execute",
+      "path": "src/request-handler.ts",
+      "startLine": 10,
+      "endLine": 24,
+      "description": "Application orchestration boundary"
+    },
+    {
+      "id": "composition",
+      "label": "Application composition root",
+      "path": "src/application.ts",
+      "description": "File-wide dependency wiring"
+    }
+  ]
+}
+RVW_JSON
+```
+
+Set the optional `authorLabel` to an accurate current Agent name when known; otherwise omit it.
+
+Parse the successful response and report the returned `rvw://walkthrough/<uuid>` reference. Publication is passive: never claim it opened rvw, activated a document, selected a commit, or changed a tab or scroll position. The human chooses which Walkthrough and code references to open and when.
+
+## Improve an existing Walkthrough
+
+Use an in-place update when the user or a Walkthrough comment asks for a clearer or more accurate explanation. Read the current artifact first, incorporate the feedback, and send a complete replacement object containing `sourceOid`, `title`, `body`, `diagramBindings`, and every reference. Omit `authorLabel` to preserve it, or set it accurately to a string or `null`. Supply the object and close stdin in the same non-interactive invocation, using the same execution-API or quoted-heredoc pattern as publication. Run:
+
+```bash
+rvw walkthrough update '<WALKTHROUGH_URI>' --stdin --json
+```
+
+The successful response keeps the same Walkthrough ID and URI. rvw does not create or retain a previous Walkthrough version. Whole-document comments stay attached to the same identity and resolve to the current body and references. Updating is passive and must not be described as browser navigation.
+
+## Delete an unnecessary Walkthrough
+
+Deletion permanently removes the Walkthrough, its references, and every comment and reply attached to it. First run the command without `--yes` and inspect the returned counts:
+
+```bash
+rvw walkthrough delete <WALKTHROUGH_URI> --json
+```
+
+Only after the user explicitly authorizes deleting that exact Walkthrough and the reported associated feedback, run:
+
+```bash
+rvw walkthrough delete <WALKTHROUGH_URI> --yes --json
+```
+
+Never infer deletion authorization from a request to revise, replace, or republish an explanation. Retained Git commit refs may be shared by other review state and remain managed by `rvw pr reset`.

package/skills/rvw-walkthrough/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "rvw Walkthrough"
+  short_description: "Publish verifiable implementation walkthroughs"
+  default_prompt: "Use $rvw-walkthrough to publish a commit-fixed implementation walkthrough in rvw."