@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/chat/chat-manager.ts

@@ -5,12 +5,19 @@ import type { AgentRunner } from '../acpx/acpx.js'
 import type { ChatContext, ChatEvent, ChatThreadsResponse, ChatTurn } from '../contract/chat.js'
 import type { FileEntry, Repo, ReviewArtifact } from '../contract/review-artifact.js'
 import type { Settings, SettingsOverrides } from '../contract/settings.js'
+import type { ReviewKey } from '../contract/review-key.js'
 import type { ChatThread } from '../contract/state.js'
 import type { SettingsStore } from '../store/settings-store.js'
 import type { StateStore } from '../store/state-store.js'
 import { type ContextSources, renderChatContext } from './context.js'
 import { renderSeed, type SeedPaths } from './seed.js'
-import { NEW_THREAD_TITLE, nextThreadIndex, type TranscriptStore, threadName, threadTitle } from './threads.js'
+import {
+  NEW_THREAD_TITLE,
+  nextThreadIndex,
+  type TranscriptStore,
+  threadName,
+  threadTitle,
+} from './threads.js'
 
 export class ChatBusyError extends Error {
   constructor() {
@@ -32,9 +39,9 @@ export interface ChatManagerDeps {
   now: () => Date
 }
 
-/** Everything about the pull request one turn needs, resolved by the route. */
+/** Everything about the review target one turn needs, resolved by the route. */
 export interface ChatTarget {
-  prNumber: number
+  key: ReviewKey
   headSha: string
   artifact: ReviewArtifact
   files: FileEntry[]
@@ -52,13 +59,13 @@ export interface ChatSendInput {
 
 export interface ChatManager {
   effectiveSettings(): Promise<Settings>
-  threads(prNumber: number): Promise<ChatThreadsResponse>
-  createThread(prNumber: number): Promise<ChatThread>
-  selectThread(prNumber: number, name: string): Promise<ChatThread | null>
+  threads(key: ReviewKey): Promise<ChatThreadsResponse>
+  createThread(key: ReviewKey): Promise<ChatThread>
+  selectThread(key: ReviewKey, name: string): Promise<ChatThread | null>
   send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent>
   /** True when a turn was running and has been asked to stop. */
-  cancel(prNumber: number): Promise<boolean>
-  busy(prNumber: number): boolean
+  cancel(key: ReviewKey): Promise<boolean>
+  busy(key: ReviewKey): boolean
 }
 
 /** The slot a turn holds while it runs. The handle is filled in once the agent has started. */
@@ -69,7 +76,7 @@ interface RunningTurn {
 }
 
 export function createChatManager(deps: ChatManagerDeps): ChatManager {
-  const running = new Map<number, RunningTurn>()
+  const running = new Map<ReviewKey, RunningTurn>()
 
   const effectiveSettings = async (): Promise<Settings> => {
     const saved = await deps.settings.read()
@@ -80,12 +87,12 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
     }
   }
 
-  const newThread = async (prNumber: number, agent: string): Promise<ChatThread> => {
+  const newThread = async (key: ReviewKey, agent: string): Promise<ChatThread> => {
     const at = deps.now().toISOString()
     let created: ChatThread | null = null
-    await deps.state.update(prNumber, state => {
+    await deps.state.update(key, state => {
       const thread: ChatThread = {
-        name: threadName(deps.repo, prNumber, agent, nextThreadIndex(state.chat.threads)),
+        name: threadName(deps.repo, key, agent, nextThreadIndex(state.chat.threads)),
         agent,
         rev: 0,
         title: NEW_THREAD_TITLE,
@@ -102,8 +109,8 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
   }
 
   /** The thread a message goes to: the one asked for, the active one, or a fresh one. */
-  const resolveThread = async (prNumber: number, agent: string, wanted?: string): Promise<ChatThread> => {
-    const state = await deps.state.read(prNumber)
+  const resolveThread = async (key: ReviewKey, agent: string, wanted?: string): Promise<ChatThread> => {
+    const state = await deps.state.read(key)
     const byName = wanted === undefined ? undefined : state.chat.threads.find(t => t.name === wanted)
     const active =
       byName ??
@@ -112,10 +119,10 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         : state.chat.threads.find(t => t.name === state.chat.activeThread))
     // Changing the agent starts a new thread: the old session belongs to the old agent.
     if (active === undefined || active.agent !== agent) {
-      return newThread(prNumber, agent)
+      return newThread(key, agent)
     }
     if (state.chat.activeThread !== active.name) {
-      await deps.state.update(prNumber, current => ({
+      await deps.state.update(key, current => ({
         ...current,
         chat: { ...current.chat, activeThread: active.name },
       }))
@@ -128,18 +135,18 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
    * try creates the session again and sends the seed again.
    */
   const saveTurn = async (
-    prNumber: number,
+    key: ReviewKey,
     thread: ChatThread,
     userText: string,
     assistant: ChatTurn,
     seededHeadSha: string,
     reached: boolean
   ): Promise<void> => {
-    await deps.transcripts.append(prNumber, thread.name, assistant)
+    await deps.transcripts.append(key, thread.name, assistant)
     if (!reached) {
       return
     }
-    await deps.state.update(prNumber, state => ({
+    await deps.state.update(key, state => ({
       ...state,
       chat: {
         ...state.chat,
@@ -163,8 +170,8 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
    * it, so the next turn creates the session again and sends the seed with it. The revision keeps
    * counting the turns the thread has taken, which is what its title is keyed on.
    */
-  const forgetSession = async (prNumber: number, name: string): Promise<void> => {
-    await deps.state.update(prNumber, state => ({
+  const forgetSession = async (key: ReviewKey, name: string): Promise<void> => {
+    await deps.state.update(key, state => ({
       ...state,
       chat: {
         ...state.chat,
@@ -174,23 +181,27 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
   }
 
   async function* send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent> {
-    if (running.has(target.prNumber)) {
+    if (running.has(target.key)) {
       throw new ChatBusyError()
     }
     // The slot is taken before the first await, so a second request that arrives while this one
     // is still reading the settings sees a busy chat rather than starting a second agent.
     const slot: RunningTurn = { run: null, stopped: false }
-    running.set(target.prNumber, slot)
+    running.set(target.key, slot)
     try {
       yield* runTurn(target, input, slot)
     } finally {
-      running.delete(target.prNumber)
+      running.delete(target.key)
     }
   }
 
-  async function* runTurn(target: ChatTarget, input: ChatSendInput, slot: RunningTurn): AsyncIterable<ChatEvent> {
+  async function* runTurn(
+    target: ChatTarget,
+    input: ChatSendInput,
+    slot: RunningTurn
+  ): AsyncIterable<ChatEvent> {
     const settings = await effectiveSettings()
-    const thread = await resolveThread(target.prNumber, settings.agent, input.thread)
+    const thread = await resolveThread(target.key, settings.agent, input.thread)
     const seeded = thread.seededHeadSha !== target.headSha
     const at = deps.now().toISOString()
     const contextBlock = await renderChatContext(input.context, {
@@ -214,7 +225,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       })
     }
 
-    await deps.transcripts.append(target.prNumber, thread.name, {
+    await deps.transcripts.append(target.key, thread.name, {
       role: 'user',
       text: input.message,
       at,
@@ -225,7 +236,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
     // transcript is written before the events, so a reader who leaves now still finds it there.
     if (slot.stopped) {
       await saveTurn(
-        target.prNumber,
+        target.key,
         thread,
         input.message,
         { role: 'assistant', text: '', at: deps.now().toISOString(), incomplete: 'cancelled' },
@@ -248,7 +259,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       maxTurns: settings.maxTurns ?? undefined,
       // The runner scrubs the line before it gets here; this only writes it down.
       onRawLine: line => {
-        void deps.transcripts.appendEvent(target.prNumber, thread.name, line).catch(() => undefined)
+        void deps.transcripts.appendEvent(target.key, thread.name, line).catch(() => undefined)
       },
     })
     slot.run = run
@@ -306,7 +317,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         await run.cancel().catch(() => undefined)
       }
       await saveTurn(
-        target.prNumber,
+        target.key,
         thread,
         input.message,
         {
@@ -320,15 +331,15 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         answer !== '' || incomplete === undefined || incomplete === 'cancelled'
       )
       if (incomplete === 'AGENT_NO_SESSION') {
-        await forgetSession(target.prNumber, thread.name)
+        await forgetSession(target.key, thread.name)
       }
     }
   }
 
   return {
     effectiveSettings,
-    async threads(prNumber) {
-      const [state, settings] = await Promise.all([deps.state.read(prNumber), effectiveSettings()])
+    async threads(key) {
+      const [state, settings] = await Promise.all([deps.state.read(key), effectiveSettings()])
       return {
         threads: state.chat.threads.map(t => ({
           name: t.name,
@@ -340,22 +351,25 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
         agent: settings.agent,
       }
     },
-    async createThread(prNumber) {
+    async createThread(key) {
       const settings = await effectiveSettings()
-      return newThread(prNumber, settings.agent)
+      return newThread(key, settings.agent)
     },
-    async selectThread(prNumber, name) {
-      const state = await deps.state.read(prNumber)
+    async selectThread(key, name) {
+      const state = await deps.state.read(key)
       const thread = state.chat.threads.find(t => t.name === name)
       if (thread === undefined) {
         return null
       }
-      await deps.state.update(prNumber, current => ({ ...current, chat: { ...current.chat, activeThread: name } }))
+      await deps.state.update(key, current => ({
+        ...current,
+        chat: { ...current.chat, activeThread: name },
+      }))
       return thread
     },
     send,
-    async cancel(prNumber) {
-      const slot = running.get(prNumber)
+    async cancel(key) {
+      const slot = running.get(key)
       if (slot === undefined) {
         return false
       }
@@ -365,7 +379,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       await slot.run?.cancel()
       return true
     },
-    busy: prNumber => running.has(prNumber),
+    busy: key => running.has(key),
   }
 }
 

package/src/chat/context.ts

@@ -106,7 +106,10 @@ export async function renderChatContext(context: ChatContext, sources: ContextSo
  * An attention point: what it says, plus the lines it sits on. The agent needs the text to know
  * what the reader is reacting to; the lines alone leave it guessing. One context, one heading.
  */
-async function renderPoint(context: Extract<ChatContext, { kind: 'point' }>, sources: ContextSources): Promise<string> {
+async function renderPoint(
+  context: Extract<ChatContext, { kind: 'point' }>,
+  sources: ContextSources
+): Promise<string> {
   const point = sources.artifact.points.find(p => p.fingerprint === context.fingerprint)
   if (point === undefined) {
     throw new ChatContextError('this canvas has no such attention point')
@@ -140,7 +143,10 @@ async function renderLines(
 }
 
 /** The quoted lines and the hunk around them, with no heading of their own. */
-async function linesBody(context: Extract<ChatContext, { kind: 'lines' }>, sources: ContextSources): Promise<string> {
+async function linesBody(
+  context: Extract<ChatContext, { kind: 'lines' }>,
+  sources: ContextSources
+): Promise<string> {
   if (context.end < context.start) {
     throw new ChatContextError('the last line of a selection comes after the first')
   }
@@ -155,6 +161,7 @@ async function linesBody(context: Extract<ChatContext, { kind: 'lines' }>, sourc
     lines === null || lines.length === 0
       ? '_these lines are not available locally_'
       : fence(lines.map((text, i) => `${context.start + i}: ${text}`).join('\n'))
-  const hunkBlock = hunk === undefined ? '' : `\n\nThe hunk around them is \`${hunk.id}\` (\`${hunk.header}\`).`
+  const hunkBlock =
+    hunk === undefined ? '' : `\n\nThe hunk around them is \`${hunk.id}\` (\`${hunk.header}\`).`
   return `${numbered}${hunkBlock}`
 }

package/src/chat/seed.ts

@@ -42,7 +42,9 @@ export function pointsMarkdown(artifact: ReviewArtifact): string {
   if (artifact.points.length === 0) {
     return '_none_'
   }
-  return artifact.points.map(p => `- ${p.level} · ${p.kind} · ${p.title} (\`${p.path}:${p.line}\`)`).join('\n')
+  return artifact.points
+    .map(p => `- ${p.level} · ${p.kind} · ${p.title} (\`${p.path}:${p.line}\`)`)
+    .join('\n')
 }
 
 export function testsMarkdown(artifact: ReviewArtifact): string {

package/src/chat/threads.ts

@@ -1,9 +1,10 @@
 // A chat thread is one acpx session plus the transcript of what was said in it. Both are named
-// after the pull request, so two repositories never share a session and a name can never point
+// after the review target, so two repositories never share a session and a name can never point
 // outside the chat directory.
 import { appendFile, mkdir, readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { type ChatTurn, ChatTurnSchema } from '../contract/chat.js'
+import { keyToString, type ReviewKey } from '../contract/review-key.js'
 import type { Repo } from '../contract/review-artifact.js'
 import type { ChatThread } from '../contract/state.js'
 import { isNotFound } from '../store/atomic-json.js'
@@ -17,19 +18,19 @@ export function slug(value: string): string {
     .slice(0, 40)
 }
 
-export function threadName(repo: Repo, prNumber: number, agent: string, index: number): string {
-  return `pr-review-${slug(repo.owner)}-${slug(repo.name)}-${prNumber}-${slug(agent)}-t${index}`
+export function threadName(repo: Repo, key: ReviewKey, agent: string, index: number): string {
+  return `pr-review-${slug(repo.owner)}-${slug(repo.name)}-${keyToString(key)}-${slug(agent)}-t${index}`
 }
 
-const NAME_RE = /^pr-review-[a-z0-9-]+-(\d+)-[a-z0-9-]+-t(\d+)$/
+const NAME_RE = /^pr-review-[a-z0-9-]+-(\d+|branch|uncommitted)-[a-z0-9-]+-t(\d+)$/
 
-/** True when the name is one this tool could have made for this pull request. */
-export function isThreadNameFor(name: string, prNumber: number): boolean {
+/** True when the name is one this tool could have made for this target. */
+export function isThreadNameFor(name: string, key: ReviewKey): boolean {
   const m = NAME_RE.exec(name)
-  return m !== null && m[1] === String(prNumber)
+  return m !== null && m[1] === keyToString(key)
 }
 
-/** The next `t<k>`: one past the highest index already used on this pull request. */
+/** The next `t<k>`: one past the highest index already used on this target. */
 export function nextThreadIndex(threads: readonly ChatThread[]): number {
   let highest = 0
   for (const thread of threads) {
@@ -55,22 +56,22 @@ export function threadTitle(firstMessage: string): string {
 }
 
 export interface TranscriptStore {
-  dir(prNumber: number): string
-  file(prNumber: number, name: string): string
-  eventsFile(prNumber: number, name: string): string
-  read(prNumber: number, name: string): Promise<ChatTurn[]>
-  append(prNumber: number, name: string, turn: ChatTurn): Promise<void>
+  dir(key: ReviewKey): string
+  file(key: ReviewKey, name: string): string
+  eventsFile(key: ReviewKey, name: string): string
+  read(key: ReviewKey, name: string): Promise<ChatTurn[]>
+  append(key: ReviewKey, name: string, turn: ChatTurn): Promise<void>
   /** Appends one already-scrubbed acpx line to the raw event log. */
-  appendEvent(prNumber: number, name: string, line: string): Promise<void>
+  appendEvent(key: ReviewKey, name: string, line: string): Promise<void>
 }
 
-export function createTranscriptStore(prDir: (prNumber: number) => string): TranscriptStore {
-  const dir = (prNumber: number): string => path.join(prDir(prNumber), 'chat')
-  const named = (prNumber: number, name: string, suffix: string): string => {
-    if (!isThreadNameFor(name, prNumber)) {
-      throw new Error(`not a chat thread of pull request ${prNumber}: ${name}`)
+export function createTranscriptStore(prDir: (key: ReviewKey) => string): TranscriptStore {
+  const dir = (key: ReviewKey): string => path.join(prDir(key), 'chat')
+  const named = (key: ReviewKey, name: string, suffix: string): string => {
+    if (!isThreadNameFor(name, key)) {
+      throw new Error(`not a chat thread of ${keyToString(key)}: ${name}`)
     }
-    return path.join(dir(prNumber), `${name}${suffix}`)
+    return path.join(dir(key), `${name}${suffix}`)
   }
   const appendLine = async (file: string, line: string): Promise<void> => {
     await mkdir(path.dirname(file), { recursive: true })
@@ -78,12 +79,12 @@ export function createTranscriptStore(prDir: (prNumber: number) => string): Tran
   }
   return {
     dir,
-    file: (prNumber, name) => named(prNumber, name, '.jsonl'),
-    eventsFile: (prNumber, name) => named(prNumber, name, '.events.ndjson'),
-    async read(prNumber, name) {
+    file: (key, name) => named(key, name, '.jsonl'),
+    eventsFile: (key, name) => named(key, name, '.events.ndjson'),
+    async read(key, name) {
       let text: string
       try {
-        text = await readFile(named(prNumber, name, '.jsonl'), 'utf8')
+        text = await readFile(named(key, name, '.jsonl'), 'utf8')
       } catch (err) {
         if (isNotFound(err)) {
           return []
@@ -108,7 +109,7 @@ export function createTranscriptStore(prDir: (prNumber: number) => string): Tran
       }
       return turns
     },
-    append: (prNumber, name, turn) => appendLine(named(prNumber, name, '.jsonl'), JSON.stringify(turn)),
-    appendEvent: (prNumber, name, line) => appendLine(named(prNumber, name, '.events.ndjson'), line),
+    append: (key, name, turn) => appendLine(named(key, name, '.jsonl'), JSON.stringify(turn)),
+    appendEvent: (key, name, line) => appendLine(named(key, name, '.events.ndjson'), line),
   }
 }

package/src/cli.ts

@@ -18,7 +18,7 @@ import {
 import { ConfigError, loadRuntimeConfig, parsePort, readEnv, resolveRepoRoot } from './config.js'
 import { type ReviewArtifact, ReviewArtifactSchema } from './contract/review-artifact.js'
 import { createGit } from './git/git.js'
-import { createGitHubClient } from './github/gh.js'
+import { createHostClient } from './host/client.js'
 import { loadProjectConfig } from './project-config.js'
 import { checkSkill } from './review/doctor.js'
 import { type AppContext, createAppContext, readPackageVersion } from './server/context.js'
@@ -26,13 +26,27 @@ import { startServer } from './server/node-server.js'
 import { readJson } from './store/atomic-json.js'
 import { ensureDataDir } from './store/data-dir.js'
 
-const SUBCOMMANDS = ['serve', 'prepare', 'validate', 'publish', 'export', 'import', 'install-skill', 'doctor'] as const
+const SUBCOMMANDS = [
+  'serve',
+  'prepare',
+  'validate',
+  'publish',
+  'export',
+  'import',
+  'install-skill',
+  'doctor',
+] as const
 
 const USAGE = `usage: pr-review <command> [flags]
 
   serve [--port 3010] [--repo <dir>] [--data-dir <dir>] [--fixture-canvas <review.json>]
         [--agent claude|codex] [--model <id>]   (chat only; wins over .pr-review/settings.yml)
-  prepare (--pr <n> | --base <ref> --head <ref>) [--force] [--repo <dir>] [--data-dir <dir>]
+  prepare (--pr <n> | --branch | --uncommitted | --base <ref> --head <ref>) [--force]
+          [--base <ref>] [--repo <dir>] [--data-dir <dir>]
+                   (--branch reviews the current branch against the default branch, and
+                    --uncommitted reviews it with the working tree's edits and new files on top.
+                    Both are for work with no PR yet, take --base <ref> to compare against
+                    another branch, and show at /review/branch and /review/uncommitted.)
   validate <model.json|review.json> --canvas <dir> [--human] [--fix] [--repo <dir>] [--data-dir <dir>]
                    (--fix trims over-cap titles in place and reports each one)
   publish <canvasDir> --agent <id> [--model <id>] --harness claude-code|codex|other [--allow-stale]
@@ -43,7 +57,7 @@ const USAGE = `usage: pr-review <command> [flags]
   doctor [--all-checks] [--repo <dir>] [--data-dir <dir>]
 
 Every command prints one JSON line on success and { "error": { code, message, hint } } on failure.
-Exit codes: 0 ok, 1 error, 2 usage, 4 gh missing or not logged in, 5 invalid model output.
+Exit codes: 0 ok, 1 error, 2 usage, 4 gh/glab missing or not logged in, 5 invalid model output.
 `
 
 const io: CliIo = {
@@ -78,7 +92,8 @@ async function buildContext(
   )
   const projectConfig = await loadProjectConfig(config.repoRoot)
   await ensureDataDir(config.dataDir)
-  const fixtureArtifact = config.fixtureCanvasPath === null ? null : await loadFixture(config.fixtureCanvasPath)
+  const fixtureArtifact =
+    config.fixtureCanvasPath === null ? null : await loadFixture(config.fixtureCanvasPath)
   return createAppContext({ config, projectConfig, fixtureArtifact })
 }
 
@@ -115,15 +130,15 @@ async function serve(argv: string[]): Promise<number> {
   return EXIT.ok
 }
 
-/** doctor builds no AppContext: it has to answer even when the repo or `gh` is the problem. */
+/** doctor builds no AppContext: it has to answer even when the repo or host CLI is the problem. */
 async function doctorCommand(argv: string[]): Promise<number> {
   const { repo, dataDir, rest } = splitCommonFlags(argv)
   const cwd = process.cwd()
-  const git = createGit(repo === undefined ? cwd : path.resolve(cwd, repo))
   return runDoctor(
     {
-      git,
-      gh: createGitHubClient(),
+      git: createGit(repo === undefined ? cwd : path.resolve(cwd, repo)),
+      env: process.env,
+      client: host => createHostClient(host.cli),
       version: readPackageVersion(),
       acpxVersion: () => createAgentRunner().acpxVersion(),
       dataDirOverride: dataDir ?? readEnv(process.env, 'PR_REVIEW_DATA_DIR'),