@vintasoftware/pr-review-canvas 0.1.0

package/src/chat/seed.ts

@@ -0,0 +1,71 @@
+// Renders the seed that opens a chat thread: who the agent is, what the pull request changes,
+// and where the code sits on disk. The prose lives in prompts/chat-seed.md.
+import type { Pr, ReviewArtifact } from '../contract/review-artifact.js'
+import { loadPromptFile, type ProjectPrompts } from '../prompt-files.js'
+import { PROMPTS_DIR } from '../paths.js'
+
+export interface SeedPaths {
+  headDir: string
+  baseDir: string
+  patchDir: string
+  repoRoot: string
+}
+
+export async function loadSeedTemplate(dir = PROMPTS_DIR, project?: ProjectPrompts): Promise<string> {
+  return loadPromptFile('chat-seed.md', dir, project)
+}
+
+/** The pull request in six lines: what a reviewer would read before opening the diff. */
+export function prMetaMarkdown(pr: Pr): string {
+  const number = pr.number === null ? '(not opened yet)' : `#${pr.number}`
+  return [
+    `- ${number} **${pr.title}** by ${pr.author}`,
+    `- \`${pr.headRef}\` → \`${pr.baseRef}\`, head \`${pr.headSha.slice(0, 7)}\``,
+    `- ${pr.changedFiles} files changed, +${pr.additions} −${pr.deletions}`,
+  ].join('\n')
+}
+
+export function layersMarkdown(artifact: ReviewArtifact): string {
+  if (artifact.layers.length === 0) {
+    return '_none_'
+  }
+  return artifact.layers
+    .map(layer => {
+      const files = layer.files.map(f => `  - \`${f.path}\``).join('\n')
+      const other = layer.kind === 'other' ? ' (mechanical)' : ''
+      return files === '' ? `- **${layer.title}**${other}` : `- **${layer.title}**${other}\n${files}`
+    })
+    .join('\n')
+}
+
+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')
+}
+
+export function testsMarkdown(artifact: ReviewArtifact): string {
+  const rows = artifact.layers.flatMap(layer =>
+    layer.tests.map(t => {
+      const where = t.testPath === undefined ? '' : ` — \`${t.testPath}\``
+      return `- ${t.status} · ${t.behavior}${where}`
+    })
+  )
+  return rows.length === 0 ? '_none_' : rows.join('\n')
+}
+
+/** Fills the template. Every token is replaced, so a template typo shows up as a missing section. */
+export function renderSeed(template: string, artifact: ReviewArtifact, paths: SeedPaths): string {
+  const values: Record<string, string> = {
+    PR_META: prMetaMarkdown(artifact.pr),
+    LAYERS: layersMarkdown(artifact),
+    POINTS: pointsMarkdown(artifact),
+    TESTS: testsMarkdown(artifact),
+    HEAD_DIR: paths.headDir,
+    BASE_DIR: paths.baseDir,
+    PATCH_DIR: paths.patchDir,
+    REPO_ROOT: paths.repoRoot,
+  }
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (whole, token: string) => values[token] ?? whole)
+}

package/src/chat/threads.ts

@@ -0,0 +1,114 @@
+// 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
+// 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 type { Repo } from '../contract/review-artifact.js'
+import type { ChatThread } from '../contract/state.js'
+import { isNotFound } from '../store/atomic-json.js'
+
+/** Only these characters make it into a session name, so the name is also a safe file name. */
+export function slug(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .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}`
+}
+
+const NAME_RE = /^pr-review-[a-z0-9-]+-(\d+)-[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 {
+  const m = NAME_RE.exec(name)
+  return m !== null && m[1] === String(prNumber)
+}
+
+/** The next `t<k>`: one past the highest index already used on this pull request. */
+export function nextThreadIndex(threads: readonly ChatThread[]): number {
+  let highest = 0
+  for (const thread of threads) {
+    const m = NAME_RE.exec(thread.name)
+    const index = m?.[2] === undefined ? 0 : Number(m[2])
+    highest = Math.max(highest, index)
+  }
+  return highest + 1
+}
+
+/** The thread list's label for a thread, taken from its first message. */
+export const THREAD_TITLE_MAX = 60
+
+/** What a thread is called until it carries a message. */
+export const NEW_THREAD_TITLE = 'New thread'
+
+export function threadTitle(firstMessage: string): string {
+  const oneLine = firstMessage.replace(/\s+/g, ' ').trim()
+  if (oneLine === '') {
+    return NEW_THREAD_TITLE
+  }
+  return oneLine.length <= THREAD_TITLE_MAX ? oneLine : `${oneLine.slice(0, THREAD_TITLE_MAX - 1)}…`
+}
+
+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>
+  /** Appends one already-scrubbed acpx line to the raw event log. */
+  appendEvent(prNumber: number, 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}`)
+    }
+    return path.join(dir(prNumber), `${name}${suffix}`)
+  }
+  const appendLine = async (file: string, line: string): Promise<void> => {
+    await mkdir(path.dirname(file), { recursive: true })
+    await appendFile(file, `${line}\n`, 'utf8')
+  }
+  return {
+    dir,
+    file: (prNumber, name) => named(prNumber, name, '.jsonl'),
+    eventsFile: (prNumber, name) => named(prNumber, name, '.events.ndjson'),
+    async read(prNumber, name) {
+      let text: string
+      try {
+        text = await readFile(named(prNumber, name, '.jsonl'), 'utf8')
+      } catch (err) {
+        if (isNotFound(err)) {
+          return []
+        }
+        throw err
+      }
+      const turns: ChatTurn[] = []
+      for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+          continue
+        }
+        let raw: unknown
+        try {
+          raw = JSON.parse(line) as unknown
+        } catch {
+          continue
+        }
+        const parsed = ChatTurnSchema.safeParse(raw)
+        if (parsed.success) {
+          turns.push(parsed.data)
+        }
+      }
+      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),
+  }
+}

package/src/cli.ts

@@ -0,0 +1,199 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import { createAgentRunner } from './acpx/acpx.js'
+import {
+  type CliIo,
+  EXIT,
+  printErrorEnvelope,
+  reportFailure,
+  runDoctor,
+  runExport,
+  runImport,
+  runInstallSkill,
+  runPrepare,
+  runPublish,
+  runValidate,
+  splitCommonFlags,
+} from './commands.js'
+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 { loadProjectConfig } from './project-config.js'
+import { type AppContext, createAppContext, readPackageVersion } from './server/context.js'
+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 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>]
+  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]
+  install-skill [--claude-dir .claude/skills] [--codex-dir .agents/skills] [--force] [--repo <dir>]
+  export (--pr <n> | --head <ref|sha>) [--out <file|dir>] [--repo <dir>] [--data-dir <dir>]
+                   (both flags: the named commit is exported and the number stamps the zip)
+  import <zip> [--pr <n>] [--force] [--repo <dir>] [--data-dir <dir>]
+  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.
+`
+
+const io: CliIo = {
+  stdout: line => process.stdout.write(`${line}\n`),
+  stderr: line => process.stderr.write(`${line}\n`),
+}
+
+async function buildContext(
+  repo: string | undefined,
+  dataDir: string | undefined,
+  extra: {
+    port?: string | undefined
+    fixtureCanvas?: string | undefined
+    agent?: string | undefined
+    model?: string | undefined
+  } = {}
+): Promise<AppContext> {
+  const cwd = process.cwd()
+  const repoDir = repo === undefined ? cwd : path.resolve(cwd, repo)
+  const git = createGit(repoDir)
+  const config = await loadRuntimeConfig(
+    {
+      port: extra.port === undefined ? undefined : parsePort(extra.port, 0),
+      dataDir,
+      fixtureCanvas: extra.fixtureCanvas,
+      agent: extra.agent,
+      model: extra.model,
+    },
+    process.env,
+    git,
+    cwd
+  )
+  const projectConfig = await loadProjectConfig(config.repoRoot)
+  await ensureDataDir(config.dataDir)
+  const fixtureArtifact = config.fixtureCanvasPath === null ? null : await loadFixture(config.fixtureCanvasPath)
+  return createAppContext({ config, projectConfig, fixtureArtifact })
+}
+
+async function loadFixture(file: string): Promise<ReviewArtifact> {
+  const artifact = await readJson(file, ReviewArtifactSchema)
+  if (artifact === null) {
+    throw new ConfigError('BAD_REQUEST', `fixture canvas not found: ${file}`)
+  }
+  return artifact
+}
+
+async function serve(argv: string[]): Promise<number> {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      port: { type: 'string' },
+      repo: { type: 'string' },
+      'data-dir': { type: 'string' },
+      'fixture-canvas': { type: 'string' },
+      agent: { type: 'string' },
+      model: { type: 'string' },
+    },
+    strict: true,
+  })
+  const ctx = await buildContext(values.repo, values['data-dir'], {
+    port: values.port,
+    fixtureCanvas: values['fixture-canvas'],
+    agent: values.agent,
+    model: values.model,
+  })
+  startServer(ctx, line => process.stderr.write(`${line}\n`))
+  return EXIT.ok
+}
+
+/** doctor builds no AppContext: it has to answer even when the repo or `gh` 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(),
+      version: readPackageVersion(),
+      acpxVersion: () => createAgentRunner().acpxVersion(),
+      dataDirOverride: dataDir ?? readEnv(process.env, 'PR_REVIEW_DATA_DIR'),
+      exists: async file => {
+        try {
+          // A read, so a dangling symlink and a directory both answer no.
+          await readFile(file)
+          return true
+        } catch {
+          return false
+        }
+      },
+    },
+    rest,
+    io
+  )
+}
+
+async function installSkillCommand(argv: string[]): Promise<number> {
+  const { repo, rest } = splitCommonFlags(argv)
+  const cwd = process.cwd()
+  const repoRoot = await resolveRepoRoot(createGit(repo === undefined ? cwd : path.resolve(cwd, repo)))
+  return runInstallSkill({ repoRoot, cwd, platform: process.platform }, rest, io)
+}
+
+export async function main(argv: string[]): Promise<number> {
+  // `pnpm review -- --port 3011` forwards the `--` itself; drop it so parseArgs sees the flags.
+  const [command, ...rest] = argv.filter(a => a !== '--')
+  if (command === undefined || command === '--help' || command === '-h') {
+    process.stderr.write(USAGE)
+    return command === undefined ? EXIT.usage : EXIT.ok
+  }
+  if (!(SUBCOMMANDS as readonly string[]).includes(command)) {
+    printErrorEnvelope(io, 'BAD_REQUEST', `unknown command: ${command}`, 'run pr-review --help')
+    return EXIT.usage
+  }
+  try {
+    switch (command) {
+      case 'serve':
+        return await serve(rest)
+      case 'install-skill':
+        return await installSkillCommand(rest)
+      case 'doctor':
+        return await doctorCommand(rest)
+      default: {
+        const { repo, dataDir, rest: own } = splitCommonFlags(rest)
+        const ctx = await buildContext(repo, dataDir)
+        switch (command) {
+          case 'prepare':
+            return await runPrepare(ctx, own, io)
+          case 'validate':
+            return await runValidate(ctx, own, io)
+          case 'export':
+            return await runExport(ctx, own, io)
+          case 'import':
+            return await runImport(ctx, own, io)
+          default:
+            return await runPublish(ctx, own, io)
+        }
+      }
+    }
+  } catch (err) {
+    return reportFailure(io, err)
+  }
+}
+
+// Run directly (`tsx src/cli.ts …`) or through bin/pr-review.mjs, which calls main() itself.
+const invokedDirectly =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)
+if (invokedDirectly) {
+  const code = await main(process.argv.slice(2))
+  if (code !== 0) {
+    process.exit(code)
+  }
+}