tspl-cli 0.0.0-stage → 0.1.1

package/src/task/brief.js

@@ -0,0 +1,115 @@
+'use strict'
+
+const { taskText } = require('./check')
+const { conventionsFor } = require('./conventions')
+
+const LEVEL = { high: 'HIGH', medium: 'MEDIUM', low: 'LOW' }
+
+const briefFrom = (result, { keywords = [], basis = null, source = 'wizard', refined = null } = {}) => ({
+  source,
+  confidence: result.confidence,
+  keywords,
+  files: result.files.map(file => ({
+    repo: file.repo,
+    path: file.path,
+    symbols: file.symbols.map(symbol => ({ name: symbol.name, line: symbol.line || null })),
+    why: file.why.slice(0, 3),
+    similar: file.similar || [],
+    copies: file.copies || [],
+  })),
+  chains: result.chains.map(chain => chain.map(step => ({ repo: step.repo, path: step.path, detail: step.detail || null }))),
+  placement: result.placement,
+  searchSteps: result.searchSteps,
+  unknown: result.unknown,
+  basis,
+  refined,
+})
+
+const basisOf = index =>
+  Object.fromEntries(Object.values(index.repos).map(repo => [repo.name, { branch: repo.branch, commit: repo.commitSha }]))
+
+const buildBrief = (loaded, task, { keywords = [], source = 'wizard', refined = null } = {}) => {
+  const card = task.card
+  const known = new Set(loaded.graph.repos.map(repo => repo.name))
+  const scope = (card.apps || []).filter(name => known.has(name))
+  const words = keywords.map(word => String(word).trim()).filter(Boolean).slice(0, 20)
+  const result = loaded.search.find([taskText(card), ...words].join(' '), {
+    limit: 10,
+    repos: scope,
+    title: [card.what, ...words].join(' '),
+  })
+  const brief = briefFrom(result, { keywords: words, basis: basisOf(loaded.index), source, refined })
+  const seen = [...new Set([...scope, ...result.files.slice(0, 5).map(file => file.repo)])]
+  brief.conventions = conventionsFor(loaded.graph, loaded.index, { focus: seen })
+  return { result, scope, brief }
+}
+
+const renderFiles = files => {
+  const lines = []
+  files.forEach((file, i) => {
+    lines.push(`${i + 1}. ${file.repo}: ${file.path}`)
+    if (file.symbols.length) {
+      lines.push(`   look at: ${file.symbols.map(symbol => (symbol.line ? `${symbol.name} (line ${symbol.line})` : symbol.name)).join(', ')}`)
+    }
+    if (file.why.length) lines.push(`   why: ${file.why.slice(0, 3).join(' · ')}`)
+    if (file.similar && file.similar.length) lines.push(`   similar files, often changed the same way: ${file.similar.join(', ')}`)
+    if (file.copies && file.copies.length) lines.push(`   same file in other repos (check whether they change too): ${file.copies.slice(0, 4).join(', ')}`)
+  })
+  return lines
+}
+
+const scopeLine = scope => {
+  if (!scope) return 'Scope: not confirmed by the PM yet.'
+  const who = scope.userName || 'the PM'
+  const when = scope.at ? ` on ${new Date(scope.at).toLocaleString()}` : ''
+  if (scope.confirmed) return `Scope: confirmed by ${who}${when}.${scope.note ? ` "${scope.note}"` : ''}`
+  return `Scope: sent back by ${who}${when}: "${scope.note || 'no note'}"`
+}
+
+const renderBrief = (task, counts, instructions = '') => {
+  const brief = task.brief
+  const { testCaseLines, TEST_NAMING } = require('../workflow/agents')
+  const cases = testCaseLines(task.card)
+  const lines = [
+    `Task ${task.id}${task.card.ticket ? ` · ${task.card.ticket}` : ''}`,
+    task.summary || taskText(task.card),
+    scopeLine(task.scope),
+    ...(cases.length ? ['', 'TEST CASES (done-when items; plan a test for each, named after its id)', ...cases, TEST_NAMING] : []),
+  ]
+  if (!brief) return (instructions ? [...lines, '', 'PROJECT RULES', instructions] : lines).join('\n')
+  lines.push('')
+  if (counts) lines.push(`tspl searched ${counts.files} files in ${counts.repos} repos (0 AI tokens).`)
+  lines.push(`Confidence: ${LEVEL[brief.confidence.level]} (${brief.confidence.reasons.join('; ')})`)
+  if (brief.keywords.length) lines.push(`Keywords: ${brief.keywords.join(', ')}`)
+  lines.push(brief.files.length ? 'Files, most relevant first:' : 'No matching files.')
+  lines.push(...renderFiles(brief.files))
+  if (brief.searchSteps && brief.searchSteps.length) {
+    lines.push('', 'Names to search for:')
+    brief.searchSteps.forEach(step => lines.push(`  ${step.pattern}   (${step.why})`))
+  }
+  if (brief.chains.length) {
+    lines.push('', 'How they connect:')
+    brief.chains.forEach(chain => {
+      lines.push(`  ${chain.map((step, i) => `${i ? ` → ${step.detail ? `${step.detail} → ` : ''}` : ''}${step.repo}: ${step.path}`).join('')}`)
+    })
+  }
+  if (brief.placement.length) {
+    lines.push('', 'New files, if needed, usually go:')
+    brief.placement.forEach(place => lines.push(`  ${place.repo}: ${place.pattern} (${place.count} like this)`))
+  }
+  if (brief.conventions && brief.conventions.length) lines.push('', ...brief.conventions)
+  if (brief.basis) {
+    lines.push('', `Based on the last fetched commit of: ${Object.entries(brief.basis).map(([name, at]) => `${name}@${at.branch}`).join(', ')}. Local, uncommitted changes are not included.`)
+  }
+  if (brief.refined && brief.refined.note) lines.push(`AI note (${brief.refined.engine}): ${brief.refined.note}`)
+  if (instructions) lines.push('', 'PROJECT RULES (.tspl/instructions.md and the files it lists)', instructions)
+  return lines.join('\n')
+}
+
+module.exports = {
+  LEVEL,
+  briefFrom,
+  buildBrief,
+  renderFiles,
+  renderBrief,
+}

package/src/task/build.js

@@ -0,0 +1,549 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+const { execFileSync, spawnSync } = require('child_process')
+
+const { request } = require('../api-client')
+const { readActive, writeActive, readTask, writeTask } = require('../config-store')
+const { remoteUrl, normalizeGitUrl } = require('../git-helper')
+const { TEST_FILE, checkFiles } = require('./gate')
+const { installHooks, removeHooks } = require('./hooks')
+
+const FETCH_TIMEOUT = 60 * 1000
+const TEST_TIMEOUT = 10 * 60 * 1000
+const TEST_TAIL = 12
+const BRANCH_WORDS = 6
+const BRANCH_LENGTH = 60
+
+const git = (dir, args, timeout) =>
+  execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout }).trim()
+
+const tryGit = (dir, args, timeout) => {
+  try {
+    return git(dir, args, timeout)
+  } catch (err) {
+    return null
+  }
+}
+
+const planFiles = plan =>
+  ['edit', 'create', 'remove']
+    .flatMap(kind => (plan && plan[kind]) || [])
+    .map(item => item.file)
+    .concat(((plan && plan.tests) || []).map(test => test.file).filter(Boolean))
+
+const planRepos = plan => [...new Set(['edit', 'create', 'remove'].flatMap(kind => (plan && plan[kind]) || []).map(item => item.file.split('/')[0]))]
+
+const suggestBranch = (card, taskKey) => {
+  const prefix = (card.ticket || taskKey).replace(/[^A-Za-z0-9-]+/g, '-')
+  const words = String(card.what || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, ' ')
+    .split(/\s+/)
+    .filter(word => word.length > 1)
+    .slice(0, BRANCH_WORDS)
+  return [prefix, ...words].join('-').slice(0, BRANCH_LENGTH).replace(/-+$/, '')
+}
+
+const validBranch = name => tryGit('.', ['check-ref-format', '--branch', name]) !== null
+
+const statusLines = dir => {
+  try {
+    return execFileSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split('\n')
+      .filter(Boolean)
+  } catch (err) {
+    return []
+  }
+}
+
+const repoState = dir => {
+  const lines = statusLines(dir)
+  return {
+    current: tryGit(dir, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    changed: lines.filter(line => !line.startsWith('??')).map(line => line.slice(3)),
+    untracked: lines.filter(line => line.startsWith('??')).length,
+  }
+}
+
+const prepareBuild = ({ taskKey, task, project, paths, branch, base: everyBase, bases = {}, fromCurrent = false }) => {
+  const repos = planRepos(task.plan).map(name => {
+    const path = paths.get(name)
+    if (!path) throw new Error(`${name} is on the plan but is not linked on this computer; run tspl in the project folder`)
+    const state = repoState(path)
+    const saved = ((project && project.repos) || []).find(repo => repo.name === name)
+    const base = bases[name] || everyBase || (fromCurrent ? state.current : (saved && saved.defaultBaseBranch) || 'master')
+    return { name, path, base, ...state, moved: moved({ name, path, base }, task.plan) }
+  })
+  return {
+    branch: branch || (task.build && task.build.branch) || suggestBranch(task.card || {}, taskKey),
+    repos,
+  }
+}
+
+const moved = (repo, plan) => {
+  const basis = plan && plan.basis && plan.basis[repo.name]
+  if (!basis || !basis.commit) return 0
+  const tip = tryGit(repo.path, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${repo.base}`])
+  if (!tip || tip === basis.commit) return 0
+  return Number(tryGit(repo.path, ['rev-list', '--count', `${basis.commit}..${tip}`])) || 0
+}
+
+const describeProposal = proposal =>
+  [
+    `Branch: ${proposal.branch}`,
+    ...proposal.repos.map(repo =>
+      `  ${repo.name}: from ${repo.base} (now on ${repo.current})` +
+        `${repo.changed.length ? ` · ${repo.changed.length} uncommitted change(s): ${repo.changed.slice(0, 3).join(', ')}` : ''}` +
+        `${repo.untracked ? ` · ${repo.untracked} untracked file(s)` : ''}` +
+        `${repo.moved ? ` · ${repo.base} has ${repo.moved} new commit(s) since the plan was made; check the plan still fits` : ''}`),
+  ].join('\n')
+
+const blockers = proposal => {
+  const problems = []
+  if (!validBranch(proposal.branch)) problems.push(`"${proposal.branch}" is not a valid branch name`)
+  proposal.repos
+    .filter(repo => repo.changed.length && repo.current !== proposal.branch)
+    .forEach(repo => problems.push(`${repo.name} has uncommitted changes (${repo.changed.slice(0, 3).join(', ')}); commit or stash them first`))
+  return problems
+}
+
+const startBranch = (repo, branch) => {
+  const notes = []
+  if (tryGit(repo.path, ['fetch', 'origin', repo.base], FETCH_TIMEOUT) === null) notes.push('could not fetch, used the local copy')
+  const ref = tryGit(repo.path, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${repo.base}`])
+    ? `origin/${repo.base}`
+    : tryGit(repo.path, ['rev-parse', '--verify', '--quiet', `refs/heads/${repo.base}`])
+      ? repo.base
+      : null
+  if (!ref) throw new Error(`${repo.name}: base branch "${repo.base}" not found`)
+  if (tryGit(repo.path, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])) {
+    if (repo.current !== branch) git(repo.path, ['switch', branch])
+    notes.push('branch already existed, switched to it')
+  } else {
+    git(repo.path, ['switch', '-c', branch, ref])
+  }
+  return { name: repo.name, path: repo.path, base: repo.base, baseSha: git(repo.path, ['rev-parse', ref]), notes }
+}
+
+const runBuild = async ({ projectId, taskKey, task, proposal }) => {
+  const problems = blockers(proposal)
+  if (problems.length) {
+    return { started: false, problems }
+  }
+  const repos = proposal.repos.map(repo => startBranch(repo, proposal.branch))
+  const build = {
+    branch: proposal.branch,
+    repos: repos.map(({ name, base, baseSha }) => ({ name, base, baseSha })),
+    startedAt: new Date().toISOString(),
+  }
+  const saved = await request('PUT', `/api/v1/projects/${projectId}/tasks/${taskKey}`, {
+    card: task.card,
+    assumptions: task.assumptions || [],
+    found: task.found || [],
+    used: task.used || [],
+    build,
+  })
+  const active = readActive()
+  active[taskKey] = {
+    projectId: String(projectId),
+    ticket: (task.card && task.card.ticket) || null,
+    branch: proposal.branch,
+    repos: repos.map(({ name, path, base, baseSha }) => ({ name, path, base, baseSha })),
+    files: planFiles(task.plan),
+    startedAt: build.startedAt,
+  }
+  writeActive(active)
+  repos.forEach(repo => {
+    try {
+      installHooks(repo.path)
+      repo.notes.push('commits and pushes are checked against the checklist')
+    } catch (err) {
+      repo.notes.push(`could not install the git hooks: ${err.message}`)
+    }
+  })
+  const local = readTask(taskKey)
+  if (local.id) writeTask({ ...local, status: saved.status, build })
+  return { started: true, repos }
+}
+
+const checkBuild = ({ taskKey, build, paths }) =>
+  (build.repos || []).map(entry => {
+    const dir = paths.get(entry.name)
+    if (!dir) return { name: entry.name, missing: true, allow: false, reasons: [`${entry.name} is not linked on this computer`], files: [] }
+    const files = (tryGit(dir, ['-c', 'core.quotePath=false', 'diff', '--name-only', `${entry.baseSha || entry.base}..HEAD`]) || '').split('\n').filter(Boolean)
+    const branch = tryGit(dir, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    return { name: entry.name, files, ...checkFiles({ taskKey, build, repoName: entry.name, branch, files }) }
+  })
+
+const tail = text => String(text || '').trim().split('\n').filter(Boolean).slice(-TEST_TAIL).join('\n')
+
+const runPlanTests = ({ task, paths }) => {
+  const build = task.build || {}
+  const tests = ((task.plan && task.plan.tests) || []).filter(test => test.command)
+  return tests.map(test => {
+    const repo = (test.file && test.file.split('/')[0]) || ((build.repos || [])[0] || {}).name
+    const dir = paths.get(repo)
+    if (!dir) return { name: test.name, passed: false, how: `${test.command} → ${repo || 'repo'} is not linked on this computer`, command: test.command, exitCode: null, executed: true }
+    const run = spawnSync('sh', ['-c', test.command], { cwd: dir, encoding: 'utf8', timeout: TEST_TIMEOUT, env: { ...process.env, CI: '1' } })
+    const exitCode = run.status === null ? -1 : run.status
+    const output = tail(`${run.stdout || ''}\n${run.stderr || ''}`)
+    return {
+      name: test.name,
+      passed: exitCode === 0,
+      how: `${test.command} → exit ${exitCode}${run.error ? ` (${run.error.message})` : ''}${output ? `\n${output}` : ''}`,
+      command: test.command,
+      exitCode,
+      executed: true,
+    }
+  })
+}
+
+const STYLE_FILE = /\.(js|jsx|ts|tsx|mjs|cjs|json|scss|css|html|md|vue)$/
+const LINT_FILE = /\.(js|jsx|ts|tsx|mjs|cjs|vue)$/
+const ESLINT_CONFIG = /^(eslint\.config\.[cm]?js|\.eslintrc(\.(js|cjs|json|ya?ml))?)$/
+const PRETTIER_CONFIG = /^(\.prettierrc(\.(js|cjs|json|ya?ml))?|prettier\.config\.[cm]?js)$/
+
+const hasConfig = (dir, pattern) => {
+  try {
+    return Fs.readdirSync(dir).some(name => pattern.test(name))
+  } catch (err) {
+    return false
+  }
+}
+
+const styleTool = (dir, name, pattern) => {
+  const bin = Path.join(dir, 'node_modules', '.bin', name)
+  return Fs.existsSync(bin) && hasConfig(dir, pattern) ? bin : null
+}
+
+const lintMessages = (bin, dir, args, input) => {
+  const run = spawnSync(bin, ['--format', 'json', ...args], { cwd: dir, encoding: 'utf8', timeout: TEST_TIMEOUT, input, maxBuffer: 64 * 1024 * 1024 })
+  try {
+    return JSON.parse(run.stdout || '[]').flatMap(result =>
+      (result.messages || []).filter(message => message.severity === 2).map(message => ({ key: `${message.ruleId}|${message.message}`, line: message.line, text: `${message.ruleId || 'error'}: ${message.message}` })))
+  } catch (err) {
+    return null
+  }
+}
+
+const newMessages = (current, base) => {
+  const seen = new Map()
+  base.forEach(message => seen.set(message.key, (seen.get(message.key) || 0) + 1))
+  return current.filter(message => {
+    const left = seen.get(message.key) || 0
+    if (left > 0) {
+      seen.set(message.key, left - 1)
+      return false
+    }
+    return true
+  })
+}
+
+const baseContent = (dir, baseSha, file) => {
+  try {
+    return execFileSync('git', ['-C', dir, 'show', `${baseSha}:${file}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
+  } catch (err) {
+    return null
+  }
+}
+
+const lintCheck = ({ repo, dir, baseSha, files, bin }) => {
+  const fresh = []
+  let old = 0
+  let broken = null
+  files.forEach(file => {
+    const current = lintMessages(bin, dir, [file])
+    if (current === null) {
+      broken = file
+      return
+    }
+    const before = baseContent(dir, baseSha, file)
+    const base = before === null ? [] : lintMessages(bin, dir, ['--stdin', '--stdin-filename', file], before) || []
+    const added = newMessages(current, base)
+    old += current.length - added.length
+    fresh.push(...added.map(message => `${file}:${message.line} ${message.text}`))
+  })
+  const passed = !fresh.length && !broken
+  return {
+    name: `lint (${repo}, ${files.length} changed file${files.length === 1 ? '' : 's'})`,
+    passed,
+    how: broken
+      ? `eslint could not check ${broken}`
+      : `eslint on the changed files → ${fresh.length} new error${fresh.length === 1 ? '' : 's'}${old ? `, ${old} already there before the change (ignored)` : ''}${fresh.length ? `\n${fresh.slice(0, TEST_TAIL).join('\n')}` : ''}`,
+    command: `eslint ${files.join(' ')}`.slice(0, 200),
+    exitCode: passed ? 0 : 1,
+    executed: true,
+  }
+}
+
+const formatCheck = ({ repo, dir, baseSha, files, bin }) => {
+  const unformatted = []
+  const legacy = []
+  files.forEach(file => {
+    const check = spawnSync(bin, ['--check', file], { cwd: dir, encoding: 'utf8', timeout: TEST_TIMEOUT })
+    if (check.status === 0) return
+    const before = baseContent(dir, baseSha, file)
+    if (before === null) {
+      unformatted.push(file)
+      return
+    }
+    const formatted = spawnSync(bin, ['--stdin-filepath', file], { cwd: dir, encoding: 'utf8', timeout: TEST_TIMEOUT, input: before, maxBuffer: 64 * 1024 * 1024 })
+    if (formatted.status === 0 && formatted.stdout.trim() === before.trim()) unformatted.push(file)
+    else legacy.push(file)
+  })
+  return {
+    name: `format (${repo}, ${files.length} changed file${files.length === 1 ? '' : 's'})`,
+    passed: !unformatted.length,
+    how: `prettier --check on the changed files → ${unformatted.length ? `not formatted: ${unformatted.join(', ')}` : 'all formatted'}${legacy.length ? ` (${legacy.length} file${legacy.length === 1 ? ' was' : 's were'} not formatted before the change either; left as is)` : ''}`,
+    command: `prettier --check ${files.join(' ')}`.slice(0, 200),
+    exitCode: unformatted.length ? 1 : 0,
+    executed: true,
+  }
+}
+
+const runStyleChecks = ({ task, paths }) => {
+  const build = task.build || {}
+  return (build.repos || []).flatMap(entry => {
+    const dir = paths.get(entry.name)
+    if (!dir) return []
+    const baseSha = entry.baseSha || entry.base
+    const changed = [...changedFiles(dir, baseSha).entries()]
+      .filter(([file, status]) => status !== 'D' && STYLE_FILE.test(file) && Fs.existsSync(Path.join(dir, file)))
+      .map(([file]) => file)
+    if (!changed.length) return []
+    const checks = []
+    const eslint = styleTool(dir, 'eslint', ESLINT_CONFIG)
+    const lintable = changed.filter(file => LINT_FILE.test(file))
+    if (eslint && lintable.length) checks.push(lintCheck({ repo: entry.name, dir, baseSha, files: lintable, bin: eslint }))
+    const prettier = styleTool(dir, 'prettier', PRETTIER_CONFIG)
+    if (prettier) checks.push(formatCheck({ repo: entry.name, dir, baseSha, files: changed, bin: prettier }))
+    return checks
+  })
+}
+
+const mergeTests = (executed, reported) => [
+  ...executed,
+  ...reported.filter(test => !executed.some(item => item.name === test.name)).map(test => ({ ...test, executed: false })),
+]
+
+const renderBuildBrief = (task, repos, conventions = [], instructions = '') => {
+  const plan = task.plan || {}
+  const card = task.card || {}
+  const build = task.build || {}
+  const lines = [
+    `BUILD ${task.key || task.id}${card.ticket ? ` · ${card.ticket}` : ''} · ${card.what || ''}`,
+    `Branch ${build.branch}. Only the files below (and test files) may change; anything else is refused at commit and push.`,
+    `Stay on ${build.branch} in every repo: do not create, switch, reset or delete branches. Work on another branch is refused.`,
+    '',
+  ]
+  ;['edit', 'create', 'remove'].forEach(kind => {
+    ;(plan[kind] || []).forEach(item => lines.push(`  ${kind}: ${item.file}${item.why ? ` — ${item.why}` : ''}`))
+  })
+  if ((plan.tests || []).length) {
+    lines.push('', 'TESTS')
+    plan.tests.forEach(test => lines.push(`  ${test.name}${test.file ? ` (${test.file})` : ''}${test.command ? `  $ ${test.command}` : ''}${(test.checks || []).length ? `  → done-when ${test.checks.join(', ')}` : ''}`))
+  }
+  if ((card.doneWhen || []).length) {
+    const { testCaseLines, TEST_NAMING } = require('../workflow/agents')
+    lines.push('', 'TEST CASES (done-when items)', ...testCaseLines(card), TEST_NAMING)
+  }
+  if (plan.notes) lines.push('', `NOTES: ${plan.notes}`)
+  if (conventions.length) lines.push('', ...conventions)
+  if (instructions) lines.push('', 'PROJECT RULES', instructions)
+  lines.push('', 'REPOS')
+  ;(repos || build.repos || []).forEach(repo => lines.push(`  ${repo.name}: ${repo.path || ''} (from ${repo.base}${repo.baseSha ? `@${String(repo.baseSha).slice(0, 7)}` : ''})`))
+  lines.push(
+    '',
+    'Build the checklist the way the surrounding code is written. Run the tests. Check every "done when" item.',
+    `Do not commit or push. When the checklist is done, call the tspl tool finish_build with taskId "${task.key || task.id}": tspl runs the test commands itself on the files as they are now and compares the changes with the checklist. Committing and pushing is the developer's own choice afterwards.`,
+  )
+  return lines.join('\n')
+}
+
+const KINDS = { edit: 'M', create: 'A', remove: 'D' }
+
+const changedFiles = (dir, baseSha) => {
+  const changed = new Map()
+  ;(tryGit(dir, ['-c', 'core.quotePath=false', 'diff', '--name-status', '--no-renames', baseSha]) || '')
+    .split('\n')
+    .filter(Boolean)
+    .forEach(line => {
+      const [status, file] = line.split('\t')
+      changed.set(file, status[0])
+    })
+  ;(tryGit(dir, ['-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard']) || '')
+    .split('\n')
+    .filter(Boolean)
+    .forEach(file => changed.set(file, 'A'))
+  return changed
+}
+
+const pullRequestLink = (dir, branch, base) => {
+  const url = remoteUrl(dir)
+  if (!url) return null
+  const path = normalizeGitUrl(url)
+  const [host, ...rest] = path.split('/')
+  const repo = rest.join('/')
+  if (host === 'github.com') return `https://github.com/${repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1`
+  if (host === 'bitbucket.org') return `https://bitbucket.org/${repo}/pull-requests/new?source=${encodeURIComponent(branch)}&dest=${encodeURIComponent(base)}`
+  if (host.includes('gitlab')) return `https://${host}/${repo}/-/merge_requests/new?merge_request[source_branch]=${encodeURIComponent(branch)}&merge_request[target_branch]=${encodeURIComponent(base)}`
+  return null
+}
+
+const reviewBuild = ({ task, paths, checks = [], tests = [] }) => {
+  const build = task.build || {}
+  const plan = task.plan || {}
+  const doneWhen = (task.card && task.card.doneWhen) || []
+  const planned = new Map(['edit', 'create', 'remove'].flatMap(kind => (plan[kind] || []).map(item => [item.file, kind])))
+  const plannedTests = new Set((plan.tests || []).map(test => test.file).filter(Boolean))
+
+  const repos = (build.repos || []).map(entry => {
+    const dir = paths.get(entry.name)
+    if (!dir) return { name: entry.name, missing: true, changed: [], commits: [] }
+    const changed = [...changedFiles(dir, entry.baseSha || entry.base).entries()].map(([file, status]) => ({ file: `${entry.name}/${file}`, status }))
+    const commits = (tryGit(dir, ['log', '--format=%h %s', `${entry.baseSha || entry.base}..HEAD`]) || '').split('\n').filter(Boolean)
+    const current = tryGit(dir, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    const pushed = tryGit(dir, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${build.branch}`])
+    const head = tryGit(dir, ['rev-parse', 'HEAD'])
+    return {
+      name: entry.name,
+      base: entry.base,
+      baseSha: entry.baseSha,
+      onBranch: current === build.branch,
+      uncommitted: statusLines(dir).length,
+      pushed: Boolean(pushed) && pushed === head,
+      push: `git -C ${dir} push -u origin ${build.branch}`,
+      pullRequest: pullRequestLink(dir, build.branch, entry.base),
+      changed,
+      commits,
+    }
+  })
+
+  const changed = new Map(repos.flatMap(repo => repo.changed.map(item => [item.file, item.status])))
+  const offPlan = [...changed.keys()].filter(file => !planned.has(file) && !plannedTests.has(file) && !TEST_FILE.test(file))
+  const untouched = [...planned.entries()].filter(([file]) => !changed.has(file)).map(([file, kind]) => `${kind} ${file}`)
+  const wrongKind = [...planned.entries()]
+    .filter(([file, kind]) => changed.has(file) && changed.get(file) !== KINDS[kind])
+    .map(([file, kind]) => `${file}: planned to ${kind}, but it was ${{ A: 'added', M: 'changed', D: 'deleted' }[changed.get(file)] || 'changed'}`)
+  const testFiles = [...changed.keys()].filter(file => plannedTests.has(file) || TEST_FILE.test(file))
+
+  const checkResults = doneWhen.map((check, i) => {
+    const reported = checks.find(item => item.n === i + 1)
+    return { n: i + 1, check, passed: Boolean(reported && reported.passed), how: reported ? reported.how || '' : 'not checked' }
+  })
+  const testResults = tests.map(test => ({ name: test.name, passed: Boolean(test.passed), how: test.how || '', ...(test.command ? { command: test.command, exitCode: test.exitCode } : {}), executed: Boolean(test.executed) }))
+
+  const problems = [
+    ...checkResults.filter(item => !item.passed).map(item => `Done-when ${item.n} "${item.check}" ${item.how === 'not checked' ? 'was not checked' : 'did not pass'}`),
+    ...testResults.filter(test => !test.passed).map(test => `Test "${test.name}" failed`),
+    ...(testResults.length ? [] : ['No test results were reported']),
+    ...offPlan.map(file => `${file} changed but is not on the approved checklist`),
+    ...repos.filter(repo => repo.missing).map(repo => `${repo.name} is not linked on this computer`),
+    ...repos.filter(repo => !repo.missing && !repo.onBranch).map(repo => `${repo.name} is not on the task branch ${build.branch}; switch back with: git -C ${paths.get(repo.name)} switch ${build.branch}`),
+  ]
+  const warnings = [
+    ...untouched.map(item => `Planned but not changed: ${item}`),
+    ...wrongKind,
+    ...repos.filter(repo => repo.uncommitted).map(repo => `${repo.name}: ${repo.uncommitted} change(s) not committed yet; tested as they are (commit and push when you want)`),
+  ]
+
+  return {
+    passed: problems.length === 0,
+    branch: build.branch,
+    checks: checkResults,
+    tests: testResults,
+    repos,
+    offPlan,
+    untouched,
+    testFiles,
+    problems,
+    warnings,
+  }
+}
+
+const describeReport = report =>
+  [
+    `REPORT · branch ${report.branch} · ${report.passed ? 'PASSED' : 'NOT DONE YET'}`,
+    '',
+    'DONE WHEN',
+    ...report.checks.map(item => `  ${item.passed ? '✓' : '✗'} ${item.n}. ${item.check}${item.how ? `  — ${item.how}` : ''}`),
+    'TESTS',
+    ...(report.tests.length ? report.tests.map(test => `  ${test.passed ? '✓' : '✗'} ${test.name}${test.how ? `  — ${test.how}` : ''}`) : ['  (none reported)']),
+    'CHANGES',
+    ...report.repos.flatMap(repo => [
+      `  ${repo.name}: ${repo.changed.length} file(s), ${repo.commits.length} commit(s) since ${repo.base}`,
+      ...repo.changed.map(item => `    ${item.status} ${item.file.slice(repo.name.length + 1)}`),
+    ]),
+    ...(report.problems.length ? ['', 'PROBLEMS', ...report.problems.map(item => `  - ${item}`)] : []),
+    ...(report.warnings.length ? ['', 'WARNINGS', ...report.warnings.map(item => `  - ${item}`)] : []),
+  ].join('\n')
+
+const finishBuild = async ({ projectId, taskKey, task, report, summary }) => {
+  const saved = await request('PUT', `/api/v1/projects/${projectId}/tasks/${taskKey}`, {
+    card: task.card,
+    assumptions: task.assumptions || [],
+    found: task.found || [],
+    used: task.used || [],
+    report: { ...report, summary: summary || '', finishedAt: new Date().toISOString() },
+  })
+  if (saved.status === 'done') {
+    const active = readActive()
+    ;((active[taskKey] || {}).repos || []).forEach(repo => removeHooks(repo.path))
+    delete active[taskKey]
+    writeActive(active)
+  }
+  const local = readTask(taskKey)
+  if (local.id) writeTask({ ...local, status: saved.status })
+  return saved
+}
+
+const stopBuild = taskKey => {
+  const active = readActive()
+  const found = Boolean(active[taskKey])
+  ;((active[taskKey] || {}).repos || []).forEach(repo => removeHooks(repo.path))
+  delete active[taskKey]
+  writeActive(active)
+  const local = readTask(taskKey)
+  if (local.id) writeTask({ ...local, status: 'stopped' })
+  return found || Boolean(local.id)
+}
+
+/**
+ * Keeps this computer's edit lock on the plan that is approved now. A build started under an earlier plan version
+ * keeps its branch, so it is not started again after an amendment; without this the hooks enforce the old checklist.
+ */
+const refreshChecklist = (taskKey, plan) => {
+  const active = readActive()
+  if (!active[taskKey] || !plan) return false
+  const files = planFiles(plan)
+  if (JSON.stringify(active[taskKey].files) === JSON.stringify(files)) return false
+  active[taskKey] = { ...active[taskKey], files, planVersion: plan.version }
+  writeActive(active)
+  return true
+}
+
+module.exports = {
+  planFiles,
+  refreshChecklist,
+  planRepos,
+  suggestBranch,
+  repoState,
+  prepareBuild,
+  describeProposal,
+  blockers,
+  runBuild,
+  startBranch,
+  stopBuild,
+  checkBuild,
+  runPlanTests,
+  runStyleChecks,
+  newMessages,
+  mergeTests,
+  renderBuildBrief,
+  reviewBuild,
+  describeReport,
+  finishBuild,
+  pullRequestLink,
+}