heyquilt 0.3.119 → 0.3.120

package/src/quilts/cli.js

@@ -4,16 +4,18 @@
 // --quilt and --square. It is not part of the Quilt app's `quilt` command.
 import path from 'node:path'
 import fs from 'node:fs'
+import os from 'node:os'
 import { quiltClient } from './client.js'
-import { findBlock, checkout, status as blockStatus, commitFolder, syncTo, localDiff, saveBlock } from './block.js'
-import { describeLog, describeShow, describeDiff, describeBlame, describeStatus, describeMerge, describeWrite, describeSquare, describeSquareStatus, describeEvents } from './describe.js'
+import { findBlock, checkout, status as blockStatus, commitFolder, amendFolder, syncTo, localDiff, saveBlock, restore, reset, clean, localChanges } from './block.js'
+import { describeLog, describeShow, describeDiff, describeBlame, describeStatus, describeMerge, describeWrite, describeSquare, describeSquareStatus, describeEvents, describeTag, describeRelease, describeImport, describeRestore, describeReset, describeClean, describeLive, describeClaims, describeResolutions, describeLiveSet, describeMergeBase, describeGrep, describeBisect, describeCheck, describeReviews, describeReviewed, describeSquareCheck, describePolicy, describeKeys, describeTokens, describeNewToken } from './describe.js'
+import { signWithLocalKey, localKey, makeLocalKey, signingKeyFile } from './signing.js'
 
 export const API_URL = 'https://api.heyquilt.com'
 
 /** The verbs `seam` answers. */
-export const SEAM_VERBS = new Set(['quilts', 'square', 'checkout', 'status', 'commit', 'log', 'show', 'diff', 'merge', 'rebase', 'revert', 'cherry-pick', 'blame', 'resolve', 'cat', 'ls', 'import', 'export', 'events'])
+export const SEAM_VERBS = new Set(['quilts', 'square', 'checkout', 'status', 'commit', 'log', 'show', 'diff', 'merge', 'rebase', 'revert', 'cherry-pick', 'blame', 'resolve', 'cat', 'ls', 'import', 'export', 'events', 'tag', 'release', 'line', 'restore', 'reset', 'clean', 'live', 'bisect', 'grep', 'describe', 'merge-base', 'claim', 'unclaim', 'check', 'resolutions', 'review', 'sign', 'key', 'token'])
 
-const VALUE_FLAGS = new Set(['-m', '--message', '-n', '--max-count', '--into', '--onto', '--on-conflict', '--quilt', '--square', '--dir', '--line', '--task', '--level', '--title', '--slug', '--format', '--expect-tip', '--side', '--file', '--batch', '--to', '--note', '--after', '--kinds', '--webhook', '--secret', '--branch'])
+const VALUE_FLAGS = new Set(['-m', '--quilts', '--message', '-n', '--max-count', '--into', '--onto', '--on-conflict', '--quilt', '--square', '--dir', '--line', '--task', '--level', '--title', '--slug', '--format', '--expect-tip', '--side', '--file', '--batch', '--to', '--note', '--after', '--kinds', '--webhook', '--secret', '--branch', '--from', '-S', '--run', '--marks', '--patch', '--on', '--path', '--checks', '--name', '--public-key'])
 
 export function parse (argv) {
   const pos = []; const flags = {}; const paths = []
@@ -61,6 +63,43 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       const list = await client.quilts()
       return print(list, list.length ? list.map((q) => `${q.slug}  ${q.id}  (${q.level})`).join('\n') : 'No quilts yet.')
     }
+    case 'line': {
+      // seam line [list] | new release/<name> [--from <rev>] | freeze <line> | unfreeze <line>
+      const sub = pos[0] || 'list'
+      const describeLine = (l) => `${l.name}: ${l.patch_count} patches, tip ${l.tip ? l.tip.slice(0, 12) : '(empty)'}${l.frozen ? ', frozen' : ''}`
+      if (sub === 'list') { const ls = await client.lines(needQuilt()); return print(ls, ls.map(describeLine).join('\n')) }
+      if (sub === 'new') {
+        if (!pos[1]) throw new Error('Name the line: seam line new release/<name> [--from <rev>]')
+        const l = await client.newLine(needQuilt(), { name: pos[1], from: flags['--from'] })
+        return print(l, `Made line ${describeLine(l)}.\nOpen a square on it with: seam square open "<title>" --line ${l.name}`)
+      }
+      if (sub === 'freeze' || sub === 'unfreeze') {
+        if (!pos[1]) throw new Error(`Which line? seam line ${sub} <line>`)
+        const l = await (sub === 'freeze' ? client.freezeLine : client.unfreezeLine)(needQuilt(), pos[1])
+        return print(l, sub === 'freeze' ? `${l.name} is frozen: merges into it are refused until seam line unfreeze ${l.name}.` : `${l.name} takes merges again.`)
+      }
+      if (sub === 'require') {
+        if (!pos[1]) throw new Error('Which line? seam line require <line> [<approvals>] [--checks ci,lint]')
+        const checks = flags['--checks'] === undefined ? undefined : String(flags['--checks']).split(',').map((c) => c.trim()).filter(Boolean)
+        if (pos[2] === undefined && checks === undefined) { const p = await client.linePolicy(needQuilt(), pos[1]); return print(p, describePolicy(p)) }
+        const p = await client.setLinePolicy(needQuilt(), pos[1], { ...(pos[2] !== undefined ? { approvals: Number(pos[2]) } : {}), ...(checks ? { checks } : {}) })
+        return print(p, describePolicy(p))
+      }
+      throw new Error('seam line [list] | new release/<name> [--from <rev>] | freeze <line> | unfreeze <line> | require <line> [<approvals>] [--checks ci,lint]')
+    }
+    case 'tag':
+    case 'release': {
+      // seam tag [<name> [rev]] | seam release [<name> [rev] -m <notes>]: no name lists them.
+      const where = (x) => `${x.short}${x.patch ? ` (${x.patch.line}:${x.patch.patch_no})` : ''}`
+      if (!pos[0]) {
+        if (cmd === 'tag') { const ts = await client.tags(needQuilt()); return print(ts, ts.length ? ts.map(describeTag).join('\n') : 'No tags yet.') }
+        const rs = await client.releases(needQuilt())
+        return print(rs, rs.length ? rs.map(describeRelease).join('\n') : 'No releases yet.')
+      }
+      if (cmd === 'tag') { const x = await client.createTag(needQuilt(), { name: pos[0], rev: pos[1] }); return print(x, `Tagged ${x.name} at ${where(x)}. Read it as tag:${x.name}.`) }
+      const x = await client.createRelease(needQuilt(), { name: pos[0], rev: pos[1], notes: flags['-m'] ?? flags['--message'] ?? '' })
+      return print(x, `Released ${x.name} at ${where(x)}. Read it as tag:${x.name}.`)
+    }
     case 'events': {
       // seam events [--after n] [--kinds a,b] | --webhook <url> [--secret s] [--kinds a,b] | --webhook off
       const kinds = flags['--kinds'] ? String(flags['--kinds']).split(',') : undefined
@@ -75,7 +114,7 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
     case 'square': {
       const sub = pos[0] || 'list'
       if (sub === 'open') {
-        const sq = await client.openSquare(needQuilt(), { title: pos.slice(1).join(' ') || flags['--title'] || 'untitled', line: flags['--line'], task_id: flags['--task'] })
+        const sq = await client.openSquare(needQuilt(), { title: pos.slice(1).join(' ') || flags['--title'] || 'untitled', line: flags['--line'], task_id: flags['--task'], ...(flags['--on'] ? { on: flags['--on'] } : {}) })
         let text = describeSquare(sq)
         if (flags['--dir']) {
           const dir = path.resolve(cwd, flags['--dir'])
@@ -130,20 +169,166 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       const st = await blockStatus(client, found.dir, block)
       return print(st, describeStatus(st))
     }
+    case 'review': {
+      // seam review [sq] (the reviews and where the square stands)
+      // seam review approve|request-changes|comment|dismiss [sq] [-m <text>] [--path <file> [--line <n>]]
+      const VERDICT = { approve: 'approve', 'request-changes': 'request_changes', comment: 'comment', dismiss: 'dismiss' }
+      const kind = VERDICT[pos[0]]
+      const sq = (kind ? pos[1] : pos[0]) || needSquare()
+      if (!kind) { const r = await client.reviews(needQuilt(), sq); return print(r, describeReviews(r)) }
+      const r = await client.review(needQuilt(), sq, { kind, body: message || '', ...(flags['--path'] ? { path: flags['--path'] } : {}), ...(flags['--line'] ? { line: Number(flags['--line']) } : {}) })
+      return print(r, describeReviewed(r))
+    }
+    case 'claim': {
+      // seam claim (lists the quilt's claims) | seam claim <pattern>... [--note <why>] (claims them for your square)
+      if (!pos.length) { const cs = await client.claims(needQuilt(), flags['--square']); return print(cs, describeClaims(cs)) }
+      const sq = needSquare()
+      const made = []
+      for (const p of pos) made.push(await client.claim(needQuilt(), sq, { pattern: p, note: flags['--note'] || message }))
+      return print(made, made.map((c) => `Claimed ${c.pattern} for ${c.square}: writes to it from other squares on ${c.line} are refused until the square merges or you run seam unclaim ${c.pattern}.`).join('\n'))
+    }
+    case 'check': {
+      // seam check <name> red|green|flaky [--line main] [--patch n] | seam check <name> green|red --square <sq>
+      const [name, status] = pos
+      if (!name || !['red', 'green', 'flaky'].includes(status)) throw new Error('seam check <name> red|green|flaky [--line <line>] [--patch <n>]')
+      if (flags['--square']) {
+        // seam check <name> green|red --square <sq>: a result for a square's latest commit (a line may require it before a merge)
+        const r = await client.reportSquareCheck(needQuilt(), flags['--square'], { check: name, status })
+        return print(r, describeSquareCheck(r))
+      }
+      const r = await client.reportCheck(needQuilt(), flags['--line'] || 'main', { check: name, status, ...(flags['--patch'] != null ? { patch: Number(flags['--patch']) } : {}) })
+      return print(r, describeCheck(r))
+    }
+    case 'unclaim': {
+      // seam unclaim <pattern|claim id>...
+      if (!pos.length) throw new Error('Which claim? seam unclaim <pattern>')
+      const sq = needSquare()
+      const out = []
+      for (const p of pos) out.push(await client.unclaim(needQuilt(), sq, p))
+      return print(out, out.map((r) => `Let go of ${r.released.pattern}.`).join('\n'))
+    }
+    case 'live': {
+      // seam live [sq] | live share (a block folder's uncommitted edits) | live clear
+      const sub = pos[0]
+      if (sub === 'share' || sub === 'clear') {
+        const sqRef = flags['--square'] || block?.square
+        if (!sqRef) throw new Error(`seam live ${sub} works in a block folder on a square (or pass --square sq:<id>).`)
+        if (sub === 'share' && !found) throw new Error('seam live share sends a block folder\'s uncommitted edits: run it in a folder made by seam checkout.')
+        const changes = sub === 'clear' ? [] : localChanges(found.dir, block).map((c) => c.status === 'deleted' ? { path: c.path, op: 'delete' } : { path: c.path, op: 'put', content: c.bytes.toString('base64'), mode: c.mode })
+        const r = await client.setLive(needQuilt(), sqRef, { changes })
+        return print(r, describeLiveSet(r))
+      }
+      const r = await client.live(needQuilt(), sub || needSquare())
+      return print(r, describeLive(r))
+    }
+    case 'restore':
+    case 'reset':
+    case 'clean': {
+      if (!found) throw new Error(`seam ${cmd} works on a block folder; run it in a folder made by seam checkout.`)
+      const files = [...(cmd === 'reset' ? pos.slice(1) : pos), ...paths].map((p) => path.resolve(cwd, p))
+      if (cmd === 'restore') { const r = await restore(client, found.dir, block, { paths: files }); return print(r, describeRestore(r)) }
+      if (cmd === 'reset') { const r = await reset(client, found.dir, block, { rev: pos[0] }); return print(r, describeReset(r, block)) }
+      const r = clean(found.dir, block, { paths: files.length ? files : [cwd], dryRun: !flags['-f'] && !flags['--force'] })
+      return print(r, describeClean(r, 'Run it again as seam clean -f to remove them.'))
+    }
     case 'commit': {
       if (!found) {
         throw new Error('seam commit seals a block folder\'s changes; run it in a folder made by seam checkout.')
       }
+      // --sign: signs the new commit with this computer's key (seam key add).
+      const signed = async (r) => {
+        if (!flags['--sign'] || !r?.result?.id) return ''
+        const s = await signWithLocalKey(client, needQuilt(), r.result.id)
+        r.signature = s.signature
+        return `\nSigned with ${s.signature.key}.`
+      }
+      if (flags['--amend']) {
+        const r = await amendFolder(client, found.dir, block, { message, paths: [...pos, ...paths].map((p) => path.resolve(cwd, p)) })
+        const s = await signed(r)
+        return print(r, describeWrite(r, `Amended ${r.amended.slice(0, 12)} as`) + s)
+      }
       if (!message) throw new Error('Say what changed: seam commit -m "message" [paths...]')
       const r = await commitFolder(client, found.dir, block, { message, paths: [...pos, ...paths].map((p) => path.resolve(cwd, p)) })
       if (r.nothing) return print(r, 'Nothing to commit.')
-      return print(r, describeWrite(r, 'Committed'))
+      const s = await signed(r)
+      return print(r, describeWrite(r, 'Committed') + s)
+    }
+    case 'sign': {
+      // seam sign [rev]: signs a commit you made (default: your square's head, or main's tip).
+      const r = await signWithLocalKey(client, needQuilt(), pos[0] || (block?.square ? block.square_short : block?.line) || 'main')
+      return print(r, `Signed ${r.short} with ${r.signature.key}.`)
+    }
+    case 'token': {
+      // seam token [list] | new <name> [--level read|write] | revoke <id or name>
+      const sub = pos[0] || 'list'
+      if (sub === 'list') { const r = await client.tokens(needQuilt()); return print(r, describeTokens(r)) }
+      if (sub === 'new') {
+        if (!pos[1]) throw new Error('seam token new <name> [--level read|write]')
+        const r = await client.createToken(needQuilt(), { name: pos[1], level: flags['--level'] || 'read' })
+        return print(r, describeNewToken(r))
+      }
+      if (sub === 'revoke') {
+        if (!pos[1]) throw new Error('seam token revoke <id or name>')
+        const r = await client.revokeToken(needQuilt(), pos[1])
+        return print(r, `Revoked token ${r.name} (${r.id}): it no longer reaches the quilt.`)
+      }
+      throw new Error('seam token [list] | new <name> [--level read|write] | revoke <id or name>')
+    }
+    case 'key': {
+      // seam key [list [member]] | add [--name <n>] [--public-key <file>] | remove <key>
+      const sub = pos[0] || 'list'
+      if (sub === 'list') { const r = await client.signingKeys({ member: pos[1] }); return print(r, describeKeys(r)) }
+      if (sub === 'remove') {
+        if (!pos[1]) throw new Error('seam key remove <key>')
+        const r = await client.removeKey(pos[1])
+        return print(r, `Removed ${r.key}: commits it signed now show "Signature by a removed key".`)
+      }
+      if (sub !== 'add') throw new Error('seam key [list [member]] | add [--name <name>] [--public-key <file>] | remove <key>')
+      let pub = flags['--public-key'] ? fs.readFileSync(path.resolve(cwd, flags['--public-key']), 'utf8') : null
+      let made = false
+      if (!pub) { const k = localKey(); if (k) pub = k.public_key; else { pub = makeLocalKey(); made = true } }
+      const r = await client.addKey({ public_key: pub, name: flags['--name'] || os.hostname() })
+      return print(r, `${made ? `Made a signing key at ${signingKeyFile()} and added` : 'Added'} ${r.key}. Sign with seam commit --sign or seam sign <rev>.`)
     }
     case 'log': {
       const rev = pos[0] || (block?.square ? block.square_short : block?.line) || 'main'
-      const r = await client.log(needQuilt(), { rev, paths, limit: flags['-n'] || flags['--max-count'] || 20 })
+      const r = await client.log(needQuilt(), { rev, paths, limit: flags['-n'] || flags['--max-count'] || 20, follow: flags['--follow'] ? true : undefined, show_signature: flags['--show-signature'] ? true : undefined, search: typeof flags['-S'] === 'string' ? flags['-S'] : undefined })
       return print(r, describeLog(r, { oneline: !!flags['--oneline'] }))
     }
+    case 'describe': {
+      const r = await client.describe(needQuilt(), pos[0] || (block?.square ? block.square_short : block?.line) || 'main')
+      return print(r, r.describe)
+    }
+    case 'merge-base': {
+      if (pos.length !== 2) throw new Error('seam merge-base <revision> <revision>')
+      const r = await client.mergeBase(needQuilt(), pos[0], pos[1])
+      return print(r, describeMergeBase(r))
+    }
+    case 'grep': {
+      // seam grep <pattern> [revision] [-- paths]: -i ignores case, -F takes the pattern as plain text, -l lists files.
+      if (!pos[0]) throw new Error('seam grep <pattern> [revision] [-i] [-F] [-l] [--all] [-- paths]')
+      if (flags['--all']) {
+        // --all: every quilt you can read (or --quilts a,b), at the revision (default main).
+        const r = await client.search({ pattern: pos[0], rev: pos[1] || 'main', quilts: flags['--quilts'] ? String(flags['--quilts']).split(',') : undefined, paths, ignore_case: flags['-i'] ? 1 : undefined, fixed: flags['-F'] ? 1 : undefined, limit: flags['--max-count'] })
+        return print(r, describeGrep(r, { filesOnly: !!flags['-l'] }))
+      }
+      const rev = pos[1] || (block?.square ? block.square_short : block?.line) || 'main'
+      const rel = (p) => found ? path.relative(found.dir, path.resolve(cwd, p)).split(path.sep).join('/') : p
+      const r = await client.grep(needQuilt(), { pattern: pos[0], rev, paths: paths.map(rel), ignore_case: flags['-i'] ? 1 : undefined, fixed: flags['-F'] ? 1 : undefined, limit: flags['--max-count'] })
+      return print(r, describeGrep(r, { filesOnly: !!flags['-l'] }))
+    }
+    case 'bisect': {
+      // seam bisect <bad> <good> --run "<check>": exit 0 good, 125 skip, else bad. Without --run, one step (--marks id:good,id:bad).
+      if (pos.length !== 2) throw new Error('seam bisect <bad> <good> --run "<check command>" (or --marks <commit>:good,<commit>:bad for one step)')
+      const marks = Object.fromEntries(String(flags['--marks'] || '').split(',').filter(Boolean).map((x) => x.split(':')))
+      if (typeof flags['--run'] === 'string') {
+        const { bisectRun } = await import('./bisect-run.js')
+        const r = await bisectRun(client, { quilt: needQuilt(), bad: pos[0], good: pos[1], run: flags['--run'], marks, api, log: (s) => { if (!json) out(s) } })
+        return print(r, describeBisect(r))
+      }
+      const r = await client.bisect(needQuilt(), { bad: pos[0], good: pos[1], marks })
+      return print(r, describeBisect(r) + (r.done ? '' : `\nThen: seam bisect ${pos[0]} ${pos[1]} --marks ${[...Object.entries(marks).map(([k, v]) => `${k}:${v}`), `${r.next.short}:<good|bad|skip>`].join(',')}`))
+    }
     case 'show': {
       const rev = pos[0] || (block?.square ? block.square_short : 'main')
       const format = flags['--stat'] ? 'stat' : flags['--name-only'] || flags['--name-status'] ? 'names' : 'unified'
@@ -206,13 +391,23 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
     }
     case 'resolve': {
       const choose = flags['--ours'] ? 'ours' : flags['--theirs'] ? 'theirs' : flags['--base'] ? 'base' : flags['--delete'] ? 'delete' : flags['--suggestion'] ? 'suggestion' : flags['--side'] != null ? Number(flags['--side']) : null
-      if (choose === null || !pos.length) throw new Error('seam resolve <path>... --ours | --theirs | --base | --suggestion | --side n | --delete (or edit the file and commit it without the markers)')
+      if (choose === null || !pos.length) throw new Error('seam resolve <path>... --ours | --theirs | --base | --suggestion | --side n | --delete [--no-remember] (or edit the file and commit it without the markers)')
       const rel = (p) => found ? path.relative(found.dir, path.resolve(cwd, p)).split(path.sep).join('/') : p
-      const r = await client.resolve(needQuilt(), needSquare(), { ...(found ? { expect_head: block.head } : {}), entries: pos.map((p) => ({ path: rel(p), choose })) })
+      const r = await client.resolve(needQuilt(), needSquare(), { ...(found ? { expect_head: block.head } : {}), entries: pos.map((p) => ({ path: rel(p), choose })), ...(flags['--no-remember'] ? { remember: false } : {}) })
       let text = describeWrite(r, 'Resolved')
       if (found) { const s = await syncTo(client, found.dir, block, r.square.head, { square: r.square }); text += `\n${s.written} file(s) updated in the folder.` }
       return print(r, text)
     }
+    case 'resolutions': {
+      // seam resolutions [path] (the remembered answers) | seam resolutions forget <key>
+      if (pos[0] === 'forget') {
+        if (!pos[1]) throw new Error('Which one? seam resolutions forget <key>')
+        const r = await client.forgetResolution(needQuilt(), pos[1])
+        return print(r, `Forgot ${r.forgotten.short} (${r.forgotten.path}): that conflict will be asked about again.`)
+      }
+      const rows = await client.resolutions(needQuilt(), pos[0])
+      return print(rows, describeResolutions(rows))
+    }
     case 'blame': {
       const arg = pos[0]
       if (!arg) throw new Error('seam blame <path>[@revision]')
@@ -236,12 +431,12 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       return print(r, r.entries.map((e) => `${e.mode}\t${e.blob ? e.blob.slice(0, 12) : e.term.slice(0, 12)}\t${e.path}`).join('\n'))
     }
     case 'import': {
-      if (pos[0] !== 'git' || !pos[1]) throw new Error('seam import git <path> [--into <new-quilt-slug>]')
+      if (pos[0] !== 'git' || !pos[1]) throw new Error('seam import git <path> [--into <quilt-slug>] [--validate]')
       const { importGit } = await import('./import-git.js')
       const repo = path.resolve(cwd, pos[1])
       if (!fs.existsSync(path.join(repo, '.git')) && !fs.existsSync(path.join(repo, 'HEAD'))) throw new Error(`${repo} is not a git repository`)
       const r = await importGit(client, { repo, slug: flags['--into'] || path.basename(repo).toLowerCase().replace(/[^a-z0-9-]/g, '-'), log: (s) => { if (!json) out(s) }, validate: !!flags['--validate'], batch: Number(flags['--batch']) || 100 })
-      return print(r, `Imported ${r.commits} commits (${r.patches} patches on main) into ${r.slug} (${r.quilt}).${r.validated != null ? ` Validated ${r.validated} trees against git.` : ''}`)
+      return print(r, describeImport(r))
     }
     case 'export': {
       if (pos[0] !== 'git' || !pos[1]) throw new Error('seam export git <dir> [--line main] [--branch <name>]')

package/src/quilts/client.js

@@ -45,6 +45,7 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     openSquare: (q, b) => call('POST', `${Q(q)}/squares`, b),
     square: (q, s) => call('GET', `${Q(q)}/squares/${enc(s)}`),
     commit: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/commit`, b),
+    amend: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/amend`, b),
     handoff: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/handoff`, b),
     abandon: (q, s, b = {}) => call('POST', `${Q(q)}/squares/${enc(s)}/abandon`, b),
     reopen: (q, s) => call('POST', `${Q(q)}/squares/${enc(s)}/reopen`, {}),
@@ -54,6 +55,16 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     rebase: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/rebase`, b),
     cherryPick: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/cherry-pick`, b),
     resolve: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/resolve`, b),
+    lines: async (q) => (await call('GET', `${Q(q)}/lines`)).lines,
+    newLine: (q, b) => call('POST', `${Q(q)}/lines`, b),
+    reportCheck: (q, line, b) => call('POST', `${Q(q)}/lines/${enc(line)}/checks`, b),
+    freezeLine: (q, line) => call('POST', `${Q(q)}/lines/${enc(line)}/freeze`, {}),
+    unfreezeLine: (q, line) => call('POST', `${Q(q)}/lines/${enc(line)}/unfreeze`, {}),
+    tags: async (q) => (await call('GET', `${Q(q)}/tags`)).tags,
+    tag: (q, name) => call('GET', `${Q(q)}/tags/${name.split('/').map(enc).join('/')}`),
+    createTag: (q, b) => call('POST', `${Q(q)}/tags`, b),
+    releases: async (q) => (await call('GET', `${Q(q)}/releases`)).releases,
+    createRelease: (q, b) => call('POST', `${Q(q)}/releases`, b),
     merge: (q, line, b) => call('POST', `${Q(q)}/lines/${enc(line)}/merge`, b),
     revert: (q, b) => call('POST', `${Q(q)}/revert`, b),
     events: (q, o = {}) => call('GET', `${Q(q)}/events${qs(o)}`),
@@ -61,15 +72,40 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     show: (q, rev, o = {}) => call('GET', `${Q(q)}/show/${enc(rev)}${qs(o)}`),
     exportPatches: (q, o = {}) => call('GET', `${Q(q)}/export/git${qs(o)}`),
     log: (q, o = {}) => call('GET', `${Q(q)}/log${qs(o)}`),
+    sign: (q, rev, b) => call('POST', `${Q(q)}/commits/${enc(rev)}/signatures`, b),
+    tokens: (q) => call('GET', `${Q(q)}/tokens`),
+    createToken: (q, b) => call('POST', `${Q(q)}/tokens`, b),
+    revokeToken: (q, id) => call('DELETE', `${Q(q)}/tokens/${enc(id)}`),
+    signingKeys: (o = {}) => call('GET', `/v1/signing-keys${qs(o)}`),
+    addKey: (b) => call('POST', '/v1/signing-keys', b),
+    removeKey: (key) => call('DELETE', `/v1/signing-keys/${enc(key)}`),
+    describe: (q, rev) => call('GET', `${Q(q)}/describe${qs({ rev })}`),
+    mergeBase: (q, a, b) => call('GET', `${Q(q)}/merge-base${qs({ a, b })}`),
+    grep: (q, o = {}) => call('GET', `${Q(q)}/grep${qs(o)}`),
+    search: (o = {}) => call('GET', `/v1/search${qs(o)}`),
+    bisect: (q, b) => call('POST', `${Q(q)}/bisect`, b),
     linePatches: (q, line = 'main', o = {}) => call('GET', `${Q(q)}/lines/${encodeURIComponent(line)}/patches${qs(o)}`),
     diff: (q, o = {}) => call('GET', `${Q(q)}/diff${qs(o)}`),
+    resolutions: async (q, p) => (await call('GET', `${Q(q)}/resolutions${p ? `?path=${enc(p)}` : ''}`)).resolutions,
+    forgetResolution: (q, key) => call('DELETE', `${Q(q)}/resolutions/${enc(key)}`),
+    reviews: (q, sq) => call('GET', `${Q(q)}/squares/${enc(sq)}/reviews`),
+    review: (q, sq, b) => call('POST', `${Q(q)}/squares/${enc(sq)}/reviews`, b),
+    reportSquareCheck: (q, sq, b) => call('POST', `${Q(q)}/squares/${enc(sq)}/checks`, b),
+    linePolicy: (q, line) => call('GET', `${Q(q)}/lines/${enc(line)}/policy`),
+    setLinePolicy: (q, line, b) => call('PUT', `${Q(q)}/lines/${enc(line)}/policy`, b),
+    claims: async (q, square) => (await call('GET', `${Q(q)}/claims${square ? `?square=${enc(square)}` : ''}`)).claims,
+    claim: (q, sq, b) => call('POST', `${Q(q)}/squares/${enc(sq)}/claims`, b),
+    unclaim: (q, sq, which) => call('DELETE', `${Q(q)}/squares/${enc(sq)}/claims/${enc(which)}`),
+    live: (q, sq) => call('GET', `${Q(q)}/squares/${enc(sq)}/live`),
+    setLive: (q, sq, body) => call('PUT', `${Q(q)}/squares/${enc(sq)}/live`, body),
     tree: (q, rev, paths) => call('GET', `${Q(q)}/tree/${enc(rev || 'main')}${qs({ paths })}`),
     cat: (q, rev, path, o = {}) => call('GET', `${Q(q)}/blob/${enc(rev || 'main')}/${pathPart(path)}${qs(o)}`),
     blame: (q, rev, path) => call('GET', `${Q(q)}/blame/${enc(rev || 'main')}/${pathPart(path)}`),
     have: (q, ids) => call('POST', `${Q(q)}/have`, { ids }),
     blobs: (q, ids) => call('POST', `${Q(q)}/blobs`, { ids }),
     uploadPack: (q, bytes) => call('POST', `${Q(q)}/packs`, bytes, { raw: true }),
-    importCommits: (q, items) => call('POST', `${Q(q)}/import/commits`, { items }),
+    importCommits: (q, items, lines = []) => call('POST', `${Q(q)}/import/commits`, { items, ...(lines.length ? { lines } : {}) }),
+    importKnown: (q, shas) => call('POST', `${Q(q)}/import/known`, { shas }),
 
     /**
      * Uploads objects the server does not have yet ([{ kind, id, bytes }]), in packs of at most

package/src/quilts/describe.js

@@ -10,6 +10,7 @@ export function describeSquare (s) {
   if (s.state === 'merged' && s.merged) bits.push(`as ${patchName(s.merged)}`)
   if (s.state === 'open') {
     bits.push(s.head ? `head ${s.head.slice(0, 12)}` : 'no commits yet')
+    if (s.on) bits.push(`stacked on ${s.on}`)
     if (s.behind_by) bits.push(`${s.behind_by} patch${s.behind_by === 1 ? '' : 'es'} behind ${s.line}`)
     if (s.conflicted_paths) bits.push(`${s.conflicted_paths} conflicted path${s.conflicted_paths === 1 ? '' : 's'}`)
   }
@@ -20,8 +21,8 @@ export function describeSquare (s) {
 export function describeLog (r, { oneline = false } = {}) {
   if (!r.commits.length) return 'No commits.'
   const lines = r.commits.map((c) => oneline
-    ? `${c.short} ${c.patch ? `[${c.patch.line}:${c.patch.patch_no}] ` : ''}${first(c.message)}`
-    : [`commit ${c.id}${c.patch ? ` (${patchName(c.patch)})` : ''}`, `Square: ${c.square}`, `Author: ${c.author.name} <${c.author.member_id}>${c.author.tool ? ` via ${c.author.tool}` : ''}`, `Date:   ${when(c.authored_at)}`, '', ...String(c.message || '').split('\n').map((l) => `    ${l}`), ''].join('\n'))
+    ? `${c.short} ${c.patch ? `[${c.patch.line}:${c.patch.patch_no}] ` : ''}${first(c.message)}${r.follow && c.path && c.path !== r.follow ? `  (${c.path})` : ''}${c.signature ? `  (signature: ${c.signature.status})` : ''}`
+    : [`commit ${c.id}${c.patch ? ` (${patchName(c.patch)})` : ''}`, `Square: ${c.square}`, ...(r.follow && c.path && c.path !== r.follow ? [`Path:   ${c.path}`] : []), `Author: ${c.author.name} <${c.author.member_id}>${c.author.tool ? ` via ${c.author.tool}` : ''}`, ...(c.signature ? [describeSignature(c.signature)] : []), `Date:   ${when(c.authored_at)}`, '', ...String(c.message || '').split('\n').map((l) => `    ${l}`), ''].join('\n'))
   if (r.more) lines.push(oneline ? '…' : '(more: seam log -n <count>)')
   return lines.join('\n')
 }
@@ -86,6 +87,8 @@ export function describeWrite (r, verb = 'Done') {
   const bits = [`${verb}${c && c.id ? ` ${c.short}` : ''}${c && c.message ? ` "${first(c.message)}"` : ''}`]
   if (r.square) bits.push(`square ${describeSquare(r.square)}`)
   if (r.conflicted) bits.push(`${r.conflicted} conflicted path${r.conflicted === 1 ? '' : 's'}: ${(r.terms || []).map((t) => `${t.path} (${t.kind})`).join(', ')}`)
+  const reused = (r.combined || []).filter((c) => c.how === 'reuse')
+  if (reused.length) bits.push(`Settled the way it was settled before: ${reused.map((c) => `${c.path} (by ${c.by})`).join(', ')}`)
   return bits.join('\n')
 }
 
@@ -94,7 +97,8 @@ export function describeMerge (r) {
   if (r.ok) {
     const lines = [`Merged as ${patchName(r.merged)} (${r.merged.commit.slice(0, 12)})${r.retries ? ` after ${r.retries} lost race${r.retries === 1 ? '' : 's'}` : ''}.`]
     const combined = (r.combined || []).filter((c) => c.how !== 'lines' || true)
-    if (combined.length) lines.push(`Combined with changes already on ${r.merged.line}: ${combined.map((c) => `${c.path} (${c.how})`).join(', ')}.`)
+    if (combined.length) lines.push(`Combined with changes already on ${r.merged.line}: ${combined.map((c) => c.how === 'reuse' ? `${c.path} (settled as ${c.by} settled it before)` : `${c.path} (${c.how})`).join(', ')}.`)
+    for (const k of r.restacked || []) lines.push(k.error ? `${k.square} is stacked on it and could not be moved (${k.error}): its holder rebases it.` : `Moved ${k.square}, stacked on it, onto ${r.merged.line}${k.conflicted ? ` with ${k.conflicted} conflicted path${k.conflicted === 1 ? '' : 's'}` : ''}.`)
     return lines.join('\n')
   }
   const lines = [`Not merged: ${r.refused ? r.refused.detail : r.error}.`]
@@ -118,3 +122,145 @@ export function describeEvents (r) {
   }
   return [...r.events.map(line), `(next: after=${r.after})`].join('\n')
 }
+
+/** One tag per line: name, commit, patch, and "release" when it is one. */
+export const describeTag = (x) => `${x.name}  ${x.short}${x.patch ? ` ${x.patch.line}:${x.patch.patch_no}` : ''}${x.release ? '  release' : ''}`
+/** A release and its notes, indented under it. */
+export const describeRelease = (x) => `${x.name}  ${x.short}${x.patch ? ` ${x.patch.line}:${x.patch.patch_no}` : ''}  ${String(x.at && new Date(x.at).toISOString()).slice(0, 10)} ${x.by}` +
+  (x.notes ? '\n' + x.notes.split('\n').map((l) => `  ${l}`).join('\n') : '')
+
+/** A git import's answer, the same words from the CLI and seam_import_git. */
+export function describeImport (r) {
+  const said = [`${r.again ? 'Added' : 'Imported'} ${r.commits} commits (${r.patches} patches) into ${r.slug}.`]
+  for (const l of r.lines) said.push(`  ${l.name}${l.name !== l.git ? ` (git ${l.git})` : ''}: ${l.added} new patches`)
+  if (r.tags) said.push(`  tags: ${r.tags}`)
+  for (const x of r.report) said.push(`  left out: ${x.ref || x.path || x.sha.slice(0, 12)}: ${x.note}`)
+  if (r.validated != null) said.push(`Validated ${r.validated} trees against git.`)
+  return said.join('\n')
+}
+
+export function describeRestore (r) {
+  return r.restored.length ? `Restored ${r.restored.length} file(s) to the last commit: ${r.restored.join(', ')}` : 'Nothing to restore: those files have no uncommitted edits.'
+}
+
+export function describeReset (r, block) {
+  const n = r.written + r.removed
+  const where = block.square ? 'the square' : block.line
+  return `Reset ${n} file(s) to ${String(r.rev).slice(0, 12)}.` + (r.changes ? `\n${r.changes} change(s) from ${where} show as uncommitted (seam status); commit them to keep them, or seam reset to go back.` : '')
+}
+
+export function describeClean (r, again) {
+  if (!r.removed.length) return 'Nothing to clean.'
+  if (r.dry_run) return r.removed.map((p) => `Would remove ${p}`).join('\n') + `\n${again}`
+  return `Removed ${r.removed.length} file(s): ${r.removed.join(', ')}`
+}
+
+export function describeLive (r) {
+  if (!r.changes.length) return `No uncommitted work shared for ${r.square}: ${r.square}:live is its head.`
+  return [`Uncommitted work in ${r.square}${r.by ? ` (shared by ${r.by})` : ''}, read as ${r.square}:live:`, ...r.changes.map((c) => `  ${c.status.padEnd(9)} ${c.path}`)].join('\n')
+}
+
+export function describeLiveSet (r) {
+  return r.changes.length ? `Shared ${r.changes.length} uncommitted change(s) of ${r.square}: read them as ${r.square}:live.` : `Cleared the live work of ${r.square}.`
+}
+
+const at = (c) => `${c.short || String(c.id || c.commit).slice(0, 12)}${c.patch ? ` (${c.patch.line}:${c.patch.patch_no})` : ''}`
+
+export function describeMergeBase (r) {
+  return r.commit ? `${r.commit}${r.patch ? ` (${r.patch.line}:${r.patch.patch_no})` : ''}` : 'No common history.'
+}
+
+export function describeGrep (r, { filesOnly = false } = {}) {
+  if (!r.matches.length) return 'No matches.'
+  const lines = filesOnly ? r.files : r.matches.map((m) => `${m.quilt ? m.quilt + ':' : ''}${m.path}:${m.line}:${m.text}`)
+  if (r.more) lines.push('… (more: raise the limit, or narrow by paths)')
+  if (r.skipped) lines.push(`(${r.skipped} large file(s) not searched)`)
+  return lines.join('\n')
+}
+
+export function describeBisect (r) {
+  if (r.done) {
+    const said = [`First bad: ${at(r.first_bad)} ${first(r.first_bad.message)}`]
+    if (r.maybe) said.push(`Or one of the skipped commits before it: ${r.maybe.map(at).join(', ')}`)
+    return said.join('\n')
+  }
+  return `Test ${at(r.next)} ${first(r.next.message)}: ${r.remaining} commit(s) left, about ${r.steps} step(s). Mark it good, bad or skip and ask again.`
+}
+
+/** A list of claims, one per line. */
+export function describeClaims (claims) {
+  if (!claims.length) return 'No claims.'
+  return claims.map((c) => `${c.pattern}  ${c.square} (${c.line})  ${c.holder}${c.note ? `: ${c.note}` : ''}`).join('\n')
+}
+
+export function describeCheck (r) {
+  const lines = [`${r.line}: merge window ${r.window} an hour${r.red.length ? ` (red: ${r.red.join(', ')})` : ''}.`]
+  const v = r.revert
+  if (v && v.reverted) lines.push(`Reverted patch ${r.line}:${v.patch_no} as patch ${r.line}:${v.revert_patch_no}.${v.fix_square ? ` The change is again in square ${v.fix_square.short}, held by ${v.fix_square.holder}: fix it there, commit, merge.` : ''}`)
+  else if (v) lines.push(`Did not revert patch ${r.line}:${v.patch_no}: ${(v.refused && (v.refused.detail || v.refused.code)) || 'refused'}.${v.square ? ` The revert waits in square ${v.square.short}.` : ''}`)
+  return lines.join('\n')
+}
+
+/** Remembered resolutions, one per line. */
+export function describeResolutions (rows) {
+  if (!rows.length) return 'No remembered resolutions.'
+  return rows.map((r) => `${r.short}  ${r.path}  ${r.answer === 'delete' ? 'deleted' : `kept ${r.blob.slice(0, 12)}`} (${r.how}, ${r.by})`).join('\n')
+}
+
+/** Where a square stands in review: approvals against what its line needs. */
+function describeStanding (r) {
+  const parts = [`${r.have} of ${r.need} approval${r.need === 1 ? '' : 's'}${r.approved_by.length ? ` (${r.approved_by.join(', ')})` : ''}`]
+  if (r.changes_requested_by.length) parts.push(`changes asked for by ${r.changes_requested_by.join(', ')}`)
+  for (const c of r.checks || []) if (c.required || c.status !== 'missing') parts.push(`check ${c.name} ${c.status}`)
+  parts.push(r.ready ? 'ready to merge' : 'not ready to merge')
+  return parts.join('; ')
+}
+
+/** A square's reviews, oldest first, then where it stands. */
+export function describeReviews (r) {
+  const rows = r.reviews.map((x) => {
+    const what = { approve: 'approved', request_changes: 'asked for changes', dismiss: 'dismissed their verdict', comment: 'commented' }[x.kind]
+    const where = x.path ? ` on ${x.path}${x.line ? `:${x.line}` : ''}` : ''
+    return `${x.author} ${what}${where}${x.outdated ? ' (an earlier commit)' : ''}${x.body ? `: ${x.body}` : ''}`
+  })
+  return `${r.square} on ${r.line}: ${describeStanding(r)}${rows.length ? '\n' + rows.join('\n') : '\nNo reviews yet.'}`
+}
+
+/** One review just given. */
+export function describeReviewed (r) {
+  const x = r.review
+  const what = { approve: 'Approved', request_changes: 'Asked for changes on', dismiss: 'Dismissed your verdict on', comment: 'Commented on' }[x.kind]
+  return `${what} ${x.square}${x.path ? ` at ${x.path}${x.line ? `:${x.line}` : ''}` : ''}. ${describeStanding(r)}.`
+}
+
+/** What a line needs to take a merge. */
+export function describePolicy (p) {
+  const parts = []
+  if (p.approvals) parts.push(`${p.approvals} approval${p.approvals === 1 ? '' : 's'} of a square's latest commit from someone other than its holder`)
+  if (p.checks?.length) parts.push(`check${p.checks.length === 1 ? '' : 's'} ${p.checks.join(', ')} green on it`)
+  return parts.length ? `${p.line} needs ${parts.join(' and ')} to take a merge.` : `${p.line} takes merges without approvals or checks.`
+}
+
+/** A check reported on a square. */
+export function describeSquareCheck (r) {
+  const req = r.checks.filter((c) => c.required)
+  const left = req.filter((c) => c.status !== 'green').map((c) => `${c.name} ${c.status}`)
+  return `${r.check} is ${r.status} on ${r.square} (${r.head.slice(0, 12)}).${req.length ? (left.length ? ` Its line still needs: ${left.join(', ')}.` : ' Every check its line requires is green.') : ''}`
+}
+
+const SIGNATURE_WORDS = { good: 'Good signature', bad: 'BAD signature', removed_key: 'Signature by a removed key', none: 'No signature' }
+export function describeSignature (s) {
+  return `Signed: ${SIGNATURE_WORDS[s.status] || s.status}${s.key ? ` from ${s.signer} (${s.key})` : ''}`
+}
+
+export function describeKeys (r) {
+  if (!r.keys.length) return `${r.member} has no signing keys.`
+  return r.keys.map((k) => `${k.key}${k.name ? `  ${k.name}` : ''}${k.removed_at ? `  (removed ${when(k.removed_at)})` : `  added ${when(k.added_at)}`}`).join('\n')
+}
+
+export function describeTokens (r) {
+  if (!r.tokens.length) return `${r.quilt} has no tokens. Make one with seam token new <name> [--level read|write].`
+  return r.tokens.map((t) => `${t.id}  ${t.name}  ${t.level}${t.revoked_at ? `  (revoked ${when(t.revoked_at)})` : `  made ${when(t.created_at)} by ${t.created_by}`}`).join('\n')
+}
+
+export const describeNewToken = (t) => `Made token ${t.name} (${t.level} on ${t.quilt}, id ${t.id}). Its secret, shown only this once:\n\n  ${t.token}\n\nSet it as SEAM_TOKEN (or send it as Authorization: Bearer <token>).`

package/src/quilts/dogfood.js

@@ -40,7 +40,7 @@ export async function dogfood (client, { repo, rev = 'HEAD', slug, work, keep =
 
     let t = Date.now()
     log(`Importing ${sha.slice(0, 12)} of ${repo} into ${slug}…`)
-    const imp = await importGit(client, { repo: src, slug, batch, validate: 'all', log })
+    const imp = await importGit(client, { repo: src, slug, batch, validate: 'all', log, onlyHead: true, fresh: true })
     times.import_ms = Date.now() - t
     log(`Imported ${imp.commits} commits (${imp.patches} patches); every commit's tree equals git's (${imp.validated}).`)
 

package/src/quilts/errors.js

@@ -0,0 +1,8 @@
+// What both the server and the seam client need without loading the server (service.js).
+export class QuiltError extends Error {
+  /** `code` is the wire name (04/07/12): head_moved, tip_moved, conflict, not_found, ... */
+  constructor (status, code, message, extra = {}) { super(message); this.status = status; this.code = code; this.extra = extra }
+}
+
+/** A square's short handle: sq: + the last 8 hex of its uuid (02). */
+export const squareShort = (id) => `sq:${String(id).replace(/-/g, '').slice(-8)}`

package/src/quilts/events.js

@@ -1,13 +1,12 @@
 // Events (plans/quilt-source-control/12): never written in the commit or merge transaction. The
 // events job reads the quilt's log after its cursor, derives each event and its recipients, and
 // writes them with the cursor moved in one transaction (store.addEvents); then it POSTs each one
-// to the recipients' webhooks, signed and retried the way the session's webhooks are
-// (webhooks.js). Members read theirs over HTTP (GET /v1/quilts/:q/events?after=), the CLI
-// (`quilt events`) and the MCP tool quilt_events, so an agent in any tool is woken the same way.
+// to the recipients' webhooks, signed and retried by seam's own webhook.js. Members read theirs
+// over HTTP (GET /v1/quilts/:q/events?after=), the CLI (`seam events`) and the MCP tool seam_events, so an agent in any tool is woken the same way.
 import { QuiltError, squareShort } from './service.js'
-import { makeSubscription, deliverWebhook, RETRY_DELAYS_MS } from '../webhooks.js'
+import { makeSubscription, deliverWebhook, RETRY_DELAYS_MS } from './webhook.js'
 
-export const QUILT_EVENT_KINDS = ['patch.merged', 'conflict.added', 'square.handoff']
+export const QUILT_EVENT_KINDS = ['patch.merged', 'patch.reverted', 'conflict.added', 'square.handoff']
 const MAX_DIFF_PATHS = 200
 
 export function eventOps (svc, sq, { allowLocalWebhooks = false, fetch, delays = RETRY_DELAYS_MS, log = () => {} } = {}) {
@@ -25,6 +24,21 @@ export function eventOps (svc, sq, { allowLocalWebhooks = false, fetch, delays =
   /** The events one log row causes. */
   async function derive (qid, row) {
     const out = []
+    if (row.kind === 'merge' && row.payload?.reverts) {
+      // patch.reverted: the reverted patch's holder (and whom they acted for) learns it is gone (07 step 4).
+      const c = await getCommit(qid, row.commit)
+      const gone = await store.patch(qid, row.line, Number(row.payload.reverts))
+      const orig = gone && gone.square ? await store.getSquare(gone.square) : null
+      const oc = gone ? await getCommit(qid, gone.commit).catch(() => null) : null
+      const to = [orig && !orig.import ? orig.holder : null, oc && oc.on_behalf_of].filter(Boolean)
+      if (to.length) {
+        out.push({
+          kind: 'patch.reverted', at: row.at, cause_seq: row.seq, square: orig.id, line: row.line, patch_no: Number(row.payload.reverts), by: by(c), paths: c.changes.map((ch) => ch.path).slice(0, MAX_DIFF_PATHS),
+          payload: { patch_no: Number(row.payload.reverts), revert_patch_no: row.patch_no, commit: c.id, message: c.message },
+          recipients: [...new Set(to)]
+        })
+      }
+    }
     if (row.kind === 'merge') {
       // patch.merged: to the holder and writers of every other open square on the line that changed a path the patch changed.
       const c = await getCommit(qid, row.commit)