@heyquilt/seam 0.0.0-stage → 0.1.0

package/lib/quilts/cli.js

@@ -0,0 +1,254 @@
+// `seam <verb>`, Quilt source control's own command (the @heyquilt/seam package, seam/): git's
+// command names and flags (plans/quilt-source-control/12), answered by the server. Inside a block
+// folder (.seam/block.json) the quilt and square come from the folder; elsewhere name them with
+// --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 { 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'
+
+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'])
+
+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'])
+
+export function parse (argv) {
+  const pos = []; const flags = {}; const paths = []
+  let rest = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (rest) { paths.push(a); continue }
+    if (a === '--') { rest = true; continue }
+    const eq = a.match(/^(--[\w-]+)=(.*)$/)
+    if (eq) { flags[eq[1]] = eq[2]; continue }
+    if (VALUE_FLAGS.has(a)) { flags[a] = argv[++i]; continue }
+    if (/^-n\d+$/.test(a)) { flags['-n'] = a.slice(2); continue }
+    if (a.startsWith('-') && a.length > 1) { flags[a] = true; continue }
+    pos.push(a)
+  }
+  return { pos, flags, paths }
+}
+
+/** The client for a block (or none): SEAM_API_URL / SEAM_TOKEN first, else the block's server and `token` (seam's own sign-in). */
+export function connect (block, token) {
+  const api = process.env.SEAM_API_URL || block?.api || API_URL
+  const key = process.env.SEAM_TOKEN || token
+  if (!key) throw new Error('Not signed in: run seam login, or set SEAM_TOKEN to an agent key.')
+  return { client: quiltClient({ api, token: key }), api }
+}
+
+/** Runs one verb; returns the text to print (or JSON with --json). `token` is the signed-in person's, when there is one. */
+export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, out = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n') } = {}) {
+  const { pos, flags, paths } = parse(argv)
+  const found = findBlock(cwd)
+  const block = found?.block
+  const { client, api } = connect(block, token)
+  const quilt = flags['--quilt'] || block?.quilt
+  const needQuilt = () => { if (!quilt) throw new Error('Name the quilt with --quilt <slug or id> (or run this inside a block folder).'); return quilt }
+  const needSquare = () => { const s = flags['--square'] || block?.square; if (!s) throw new Error('No square here: run this in a block folder, or pass --square sq:<id>.'); return s }
+  const json = !!flags['--json']
+  const print = (data, text) => out(json ? JSON.stringify(data, null, 2) : text)
+  const message = flags['-m'] || flags['--message']
+
+  switch (cmd) {
+    case 'quilts': {
+      if (pos[0] === 'new') { const q = await client.createQuilt({ slug: pos[1], name: flags['--title'] }); return print(q, `Made quilt ${q.slug} (${q.id}).`) }
+      if (pos[0] === 'add') { const r = await client.addMember(needQuilt(), { member_id: pos[1], level: flags['--level'] || 'write' }); return print(r, `${r.member_id}: ${r.level || 'removed'}`) }
+      if (pos[0] === 'show') { const q = await client.quilt(pos[1] || needQuilt()); return print(q, `${q.slug} (${q.id})\n${q.lines.map((l) => `  ${l.name}: ${l.patch_count} patches, tip ${l.tip ? l.tip.slice(0, 12) : '(empty)'}`).join('\n')}`) }
+      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 '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
+      if (flags['--webhook']) {
+        const off = flags['--webhook'] === 'off'
+        const r = await client.subscribe(needQuilt(), off ? { url: null } : { url: flags['--webhook'], secret: flags['--secret'], events: kinds })
+        return print(r, off ? 'Webhook removed.' : `Events (${r.events.join(', ')}) now POST to ${r.url}${r.secret ? `\nSigning secret (shown once): ${r.secret}` : ''}`)
+      }
+      const r = await client.events(needQuilt(), { after: flags['--after'], kinds })
+      return print(r, describeEvents(r))
+    }
+    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'] })
+        let text = describeSquare(sq)
+        if (flags['--dir']) {
+          const dir = path.resolve(cwd, flags['--dir'])
+          await checkout(client, { quilt: needQuilt(), square: sq.id, paths, dir, api })
+          text += `\nChecked out into ${dir}.`
+        }
+        return print(sq, text)
+      }
+      // seam square handoff [sq] --to <member> [--note text] | abandon [sq] | reopen [sq]
+      if (sub === 'handoff') { const sq = await client.handoff(needQuilt(), pos[1] || needSquare(), { to: flags['--to'], note: flags['--note'] }); return print(sq, `Handed ${sq.short || sq.id} to ${sq.holder}.`) }
+      if (sub === 'abandon') { const sq = await client.abandon(needQuilt(), pos[1] || needSquare()); return print(sq, `Abandoned ${sq.short || sq.id}; seam square reopen brings it back.`) }
+      if (sub === 'reopen') { const sq = await client.reopen(needQuilt(), pos[1] || needSquare()); return print(sq, `Reopened ${sq.short || sq.id}; you hold it.`) }
+      // seam square fold [sq] --into sq:<id> | split [sq] <paths,...> <paths,...> [--title t]
+      if (sub === 'fold') {
+        if (!flags['--into']) throw new Error('Fold into which square? seam square fold [sq:from] --into sq:<id>')
+        const r = await client.fold(needQuilt(), pos[1] || needSquare(), { into: flags['--into'], message })
+        return print(r, describeWrite(r, `Folded ${r.folded.short} into ${r.square.short}:`))
+      }
+      if (sub === 'split') {
+        const own = pos[1] && pos[1].startsWith('sq:')
+        const groups = pos.slice(own ? 2 : 1).map((g) => g.split(',').filter(Boolean))
+        if (!groups.length) throw new Error('Split by which paths? seam square split [sq] docs,README.md src (one group per new square)')
+        const r = await client.split(needQuilt(), own ? pos[1] : needSquare(), { by: 'paths', groups, ...(flags['--title'] ? { titles: [flags['--title']] } : {}) })
+        const text = [`Kept in ${r.square.short}: ${r.kept.join(', ') || '(nothing)'}`, ...r.squares.map((q) => `New ${describeSquare(q)}: ${q.paths.join(', ')}`)].join('\n')
+        if (found && block.square === r.square.id) { const st = await syncTo(client, found.dir, block, r.square.head, { square: r.square }); return print(r, `${text}\n${st.written} file(s) updated in the folder.`) }
+        return print(r, text)
+      }
+      if (sub === 'show') { const sq = await client.square(needQuilt(), pos[1] || needSquare()); return print(sq, describeSquareStatus(sq)) }
+      const list = await client.squares(needQuilt(), { state: flags['--all'] ? undefined : (flags['--state'] || 'open'), mine: !!flags['--mine'] })
+      return print(list, list.length ? list.map(describeSquare).join('\n') : 'No open squares.')
+    }
+    case 'checkout': {
+      const target = pos[0]
+      if (!target) throw new Error('seam checkout <sq:id | revision> [--dir folder] [-- paths]')
+      const isSquare = target.startsWith('sq:') && !/:(base|live)$|~\d+$/.test(target)
+      if (found && !flags['--dir']) {
+        // Switch this block to another square or revision: only from a clean folder.
+        const st = await blockStatus(client, found.dir, block)
+        if (st.changes.length) throw new Error(`This folder has ${st.changes.length} uncommitted change(s); commit them first.`)
+        const sq = isSquare ? await client.square(block.quilt, target) : null
+        const to = sq ? (sq.head || sq.base) : (await client.show(block.quilt, target, { format: 'none' })).commit.id
+        const r = await syncTo(client, found.dir, block, to, { square: sq })
+        if (!sq) { block.square = null; block.square_short = null; block.head = null; saveBlock(found.dir, block) }
+        return print(r, `Switched to ${sq ? `${sq.short} "${sq.title}"` : target} (${r.written} file(s) written).`)
+      }
+      const dir = path.resolve(cwd, flags['--dir'] || (isSquare ? target.replace(':', '-') : 'seam-checkout'))
+      const r = await checkout(client, { quilt: needQuilt(), ...(isSquare ? { square: target } : { rev: target }), paths, dir, api })
+      return print({ dir, files: r.files, block: { ...r.block, files: undefined } }, `Checked out ${r.files} file(s) of ${isSquare ? target : target} under ${r.block.paths.map((p) => p || '/').join(', ')} into ${dir}.`)
+    }
+    case 'status': {
+      if (!found) throw new Error('Not in a block folder (no .seam/block.json here or above).')
+      const st = await blockStatus(client, found.dir, block)
+      return print(st, describeStatus(st))
+    }
+    case 'commit': {
+      if (!found) {
+        throw new Error('seam commit seals a block folder\'s changes; run it in a folder made by seam checkout.')
+      }
+      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'))
+    }
+    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 })
+      return print(r, describeLog(r, { oneline: !!flags['--oneline'] }))
+    }
+    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'
+      const r = await client.show(needQuilt(), rev, { format, paths })
+      return print(r, describeShow(r, { format }))
+    }
+    case 'diff': {
+      const format = flags['--stat'] ? 'stat' : flags['--name-only'] || flags['--name-status'] ? 'names' : 'unified'
+      if (!pos.length && found) {
+        const d = await localDiff(client, found.dir, block, { paths: paths.map((p) => path.resolve(cwd, p)) })
+        return print(d, format === 'unified' ? (d.text || '') : d.changes.map((c) => `${c.status[0].toUpperCase()}\t${c.path}`).join('\n'))
+      }
+      const [from, to] = pos.length === 1 && pos[0].includes('..') ? pos[0].split('..') : pos.length === 1 ? [pos[0], block?.square ? block.square_short : 'main'] : pos
+      const r = await client.diff(needQuilt(), { from, to, paths, format })
+      return print(r, describeDiff(r, { format }))
+    }
+    case 'merge': {
+      let into = flags['--into'] || (pos.length ? null : (block?.line || 'main'))
+      // git merge <other>: in a block on a square, merges that square (or revision) into this one.
+      if (!into && block?.square) into = block.square_short || block.square
+      if (!into) throw new Error('Merge into what? seam merge sq:<id> --into main (a line) or --into sq:<id> (a square)')
+      if (/^sq:/.test(into)) {
+        const target = into
+        const from = pos[0] || needSquare()
+        const mine = found && (target === block.square_short || target === block.square)
+        const r = await client.mergeSquare(needQuilt(), target, { from, ...(mine ? { expect_head: block.head } : {}), message })
+        let text = r.noop ? `Already up to date: ${from} is in ${target}.` : describeWrite(r, `Merged ${from} into ${target}:`)
+        if (mine && !r.noop) { const st = await syncTo(client, found.dir, block, r.square.head, { square: r.square }); text += `\n${st.written} file(s) updated in the folder.` }
+        return print(r, text)
+      }
+      const sqId = pos[0] && pos[0].startsWith('sq:') ? pos[0] : needSquare()
+      const r = await client.merge(needQuilt(), into, { square: sqId, ...(found && sqId === block.square ? { expect_head: block.head } : {}), message, dry_run: !!flags['--dry-run'], on_conflict: flags['--on-conflict'], expect_tip: flags['--expect-tip'] })
+      let text = describeMerge(r)
+      // The refused merge left the square rebased onto the tip with its conflicts: bring the folder there.
+      if (found && sqId === block.square && !r.ok && r.head && r.head !== block.head) {
+        const s = await syncTo(client, found.dir, block, r.head, { square: r.square })
+        text += `\nThe folder now holds the rebased files (${s.written} written)${s.kept.length ? `; kept your own version of ${s.kept.join(', ')}` : ''}.`
+      }
+      return print(r, text)
+    }
+    case 'rebase': {
+      const r = await client.rebase(needQuilt(), needSquare(), { ...(found ? { expect_head: block.head } : {}), onto: flags['--onto'] })
+      let text = r.noop ? 'Already on the tip.' : describeWrite(r, 'Rebased')
+      if (found && !r.noop) { const s = await syncTo(client, found.dir, block, r.square.head || r.square.base, { square: r.square }); text += `\n${s.written} file(s) updated in the folder.` }
+      return print(r, text)
+    }
+    case 'cherry-pick': {
+      if (!pos[0]) throw new Error('seam cherry-pick <revision>')
+      const r = await client.cherryPick(needQuilt(), needSquare(), { from: pos[0], ...(found ? { expect_head: block.head } : {}) })
+      let text = describeWrite(r, 'Picked')
+      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 'revert': {
+      if (!pos[0]) throw new Error('seam revert <patch:n | revision>')
+      const r = await client.revert(needQuilt(), { rev: pos[0], line: flags['--line'] })
+      let text = describeWrite(r, 'Reverted in a new square') + `\nMerge it with: seam merge ${r.square.short} --into ${r.square.line}`
+      if (flags['--dir']) { const dir = path.resolve(cwd, flags['--dir']); await checkout(client, { quilt: needQuilt(), square: r.square.id, dir, api }); text += `\nChecked out into ${dir}.` }
+      return print(r, text)
+    }
+    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)')
+      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 })) })
+      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 'blame': {
+      const arg = pos[0]
+      if (!arg) throw new Error('seam blame <path>[@revision]')
+      const at = arg.lastIndexOf('@')
+      const [p, rev] = at > 0 ? [arg.slice(0, at), arg.slice(at + 1)] : [arg, pos[1] || (block?.square ? block.square_short : 'main')]
+      const rel = found && at < 0 ? path.relative(found.dir, path.resolve(cwd, p)).split(path.sep).join('/') : p
+      const r = await client.blame(needQuilt(), rev, rel)
+      return print(r, describeBlame(r))
+    }
+    case 'cat': {
+      const arg = pos[0] || ''
+      const at = arg.lastIndexOf('@')
+      const [p, rev] = at > 0 ? [arg.slice(0, at), arg.slice(at + 1)] : [arg, 'main']
+      const r = await client.cat(needQuilt(), rev, p, { format: flags['--format'] || 'diff' })
+      if (json) return print(r, '')
+      process.stdout.write(Buffer.from(r.content, 'base64'))
+      return
+    }
+    case 'ls': {
+      const r = await client.tree(needQuilt(), pos[0] || 'main', pos.slice(1).concat(paths))
+      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>]')
+      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.` : ''}`)
+    }
+    case 'export': {
+      if (pos[0] !== 'git' || !pos[1]) throw new Error('seam export git <dir> [--line main] [--branch <name>]')
+      const { exportGit } = await import('./export-git.js')
+      const r = await exportGit(client, { q: needQuilt(), dir: path.resolve(cwd, pos[1]), line: flags['--line'] || 'main', branch: flags['--branch'] || undefined, log: (s) => { if (!json) out(s) } })
+      return print(r, r.exported ? `Exported ${r.exported} patches to ${r.branch} in ${pos[1]}: ${r.branch} is ${r.sha} (patch ${r.patch_no}).` : `Nothing new: ${r.branch} is ${r.sha || 'empty'} (patch ${r.patch_no}).`)
+    }
+  }
+  throw new Error(`unknown seam command ${cmd}`)
+}

package/lib/quilts/client.js

@@ -0,0 +1,92 @@
+// The quilt API from a client (the CLI, the local MCP, the importer): one function per route.
+// A refusal throws an Error with the server's `code`, `status` and fields (head, terms, ...).
+import { buildPack } from './pack.js'
+
+const enc = encodeURIComponent
+const qs = (o) => {
+  const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && !v.length))
+  return p.length ? '?' + p.map(([k, v]) => `${k}=${enc(Array.isArray(v) ? v.join(',') : v)}`).join('&') : ''
+}
+const pathPart = (p) => String(p).split('/').map(enc).join('/')
+
+export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch, timeoutMs = 120_000 }) {
+  const base = String(api || '').replace(/\/+$/, '')
+  if (!base) throw new Error('No quilt server: set QUILT_API (or sign in with `quilt login`).')
+  const auth = token ? (token.startsWith('QuiltPass ') ? token : `Bearer ${token}`) : null
+
+  async function call (method, route, body, { raw = false } = {}) {
+    let res
+    try {
+      res = await fetchImpl(base + route, {
+        method,
+        headers: { ...(auth ? { authorization: auth } : {}), ...(body !== undefined ? { 'content-type': raw ? 'application/octet-stream' : 'application/json' } : {}) },
+        body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      })
+    } catch (err) {
+      throw new Error(`Couldn't reach the quilt server at ${base} (${err?.cause?.code || err?.name || 'no answer'}).`)
+    }
+    const data = await res.json().catch(() => null)
+    if (!res.ok && !(data && data.refused)) {
+      const { error, ...extra } = data || {}
+      throw Object.assign(new Error(error || `The quilt server answered ${res.status}.`), { status: res.status, ...extra })
+    }
+    return data
+  }
+
+  const Q = (q) => `/v1/quilts/${enc(q)}`
+  return {
+    call,
+    quilts: async () => (await call('GET', '/v1/quilts')).quilts,
+    createQuilt: (b) => call('POST', '/v1/quilts', b),
+    quilt: (q) => call('GET', Q(q)),
+    addMember: (q, b) => call('POST', `${Q(q)}/members`, b),
+    squares: async (q, f = {}) => (await call('GET', `${Q(q)}/squares${qs({ state: f.state, mine: f.mine ? 1 : undefined, task: f.task })}`)).squares,
+    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),
+    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`, {}),
+    mergeSquare: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/merge`, b),
+    fold: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/fold`, b),
+    split: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/split`, b),
+    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),
+    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)}`),
+    subscribe: (q, b) => call('POST', `${Q(q)}/webhook`, b),
+    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)}`),
+    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)}`),
+    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 }),
+
+    /**
+     * Uploads objects the server does not have yet ([{ kind, id, bytes }]), in packs of at most
+     * ~48 MiB, after asking `have` (04: want-only, one pack per commit for a typical commit).
+     */
+    async upload (q, objs) {
+      const missing = new Set()
+      for (let i = 0; i < objs.length; i += 10000) for (const id of (await call('POST', `${Q(q)}/have`, { ids: objs.slice(i, i + 10000).map((o) => o.id) })).missing) missing.add(id)
+      const todo = objs.filter((o) => missing.has(o.id))
+      let batch = []; let size = 0; let packs = 0
+      const flush = async () => { if (!batch.length) return; await call('POST', `${Q(q)}/packs`, buildPack(batch).bytes, { raw: true }); packs++; batch = []; size = 0 }
+      for (const o of todo) {
+        if (size + o.bytes.length > 48 * 1024 * 1024) await flush()
+        batch.push(o); size += o.bytes.length
+      }
+      await flush()
+      return { uploaded: todo.length, packs }
+    }
+  }
+}

package/lib/quilts/describe.js

@@ -0,0 +1,120 @@
+// The server's records as plain English (plans/quilt-source-control/12, "Every write returns the
+// server's view"): one rendering for the CLI and both MCPs, so every tool says the same thing.
+
+const when = (ms) => (ms ? new Date(ms).toISOString().replace('T', ' ').slice(0, 16) + ' UTC' : '')
+const first = (m) => String(m || '').split('\n')[0]
+const patchName = (p) => (p ? `patch ${p.line}:${p.patch_no}` : '')
+
+export function describeSquare (s) {
+  const bits = [`${s.short} "${s.title}"`, s.state]
+  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.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'}`)
+  }
+  bits.push(`held by ${s.holder}`)
+  return bits.join(' · ')
+}
+
+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'))
+  if (r.more) lines.push(oneline ? '…' : '(more: seam log -n <count>)')
+  return lines.join('\n')
+}
+
+export function describeDiff (d, { format = 'unified' } = {}) {
+  if (!d.files.length) return 'No differences.'
+  if (format === 'names') return d.files.map((f) => `${f.status[0].toUpperCase()}\t${f.path}`).join('\n')
+  if (format === 'stat') {
+    const w = Math.max(...d.files.map((f) => f.path.length))
+    return [...d.files.map((f) => ` ${f.path.padEnd(w)} | ${f.binary ? 'Bin' : `${(f.add || 0) + (f.del || 0)} ${'+'.repeat(Math.min(f.add || 0, 40))}${'-'.repeat(Math.min(f.del || 0, 40))}`}`), ` ${d.files.length} file${d.files.length === 1 ? '' : 's'} changed, ${d.add || 0} insertions(+), ${d.del || 0} deletions(-)`].join('\n')
+  }
+  return d.files.map((f) => f.binary ? `Binary file ${f.path} ${f.status}\n` : f.patch || `${f.path} ${f.status}\n`).join('')
+}
+
+export function describeShow (r, { format = 'unified' } = {}) {
+  const c = r.commit
+  const head = [`commit ${c.id}${c.patch ? ` (${patchName(c.patch)})` : ''}`]
+  if (c.parents.length > 1) head.push(`Merge: ${c.parents.map((p) => p.slice(0, 12)).join(' ')}`)
+  head.push(`Square: ${c.square}${r.square ? ` "${r.square.title}" (${r.square.state})` : ''}`)
+  head.push(`Author: ${c.author.name} <${c.author.member_id}>${c.author.tool ? ` via ${c.author.tool}` : ''}`)
+  head.push(`Date:   ${when(c.authored_at)}`)
+  if (c.predecessor) head.push(`Rewrites: ${c.predecessor.slice(0, 12)}`)
+  if (c.conflicted) head.push(`Conflicted paths in this commit: ${c.conflicted}`)
+  head.push('', ...String(c.message || '').split('\n').map((l) => `    ${l}`), '')
+  return head.join('\n') + (r.diff ? '\n' + describeDiff(r.diff, { format }) : '')
+}
+
+export function describeBlame (r) {
+  const w = Math.max(...r.lines.map((l) => (l.author || '').length), 4)
+  return r.lines.map((l) => `${(l.short || '?').slice(0, 10)} ${l.patch ? `${l.patch.line}:${l.patch.patch_no}`.padEnd(9) : (l.square || '').padEnd(9)} (${(l.author || '?').padEnd(w)} ${when(l.at).slice(0, 10)} ${String(l.line).padStart(4)}) ${l.text}`).join('\n')
+}
+
+/** A square with 06's status fields: what merged under it and what would conflict on merge. */
+export function describeSquareStatus (s, { prefix = '' } = {}) {
+  const lines = [prefix + describeSquare(s)]
+  if (s.folded_into) lines.push(`Folded into ${s.folded_into}.`)
+  const under = s.merged_under_you || []
+  if (under.length) {
+    lines.push(`Merged under you (patches since your base that changed your files)${s.merged_under_you_more ? ', newest 50' : ''}:`)
+    for (const p of under) lines.push(`  patch ${p.patch_no} by ${p.author}: ${p.message} (${p.paths.join(', ')})`)
+  }
+  const wc = s.would_conflict || []
+  if (wc.length) lines.push(`Would conflict if merged now: ${wc.map((w) => `${w.path}${w.patch_no ? ` (with patch ${w.patch_no} by ${w.author})` : ''}`).join(', ')}. Rebase (seam rebase) to settle it in your square first.`)
+  else if (under.length) lines.push('Would merge cleanly now.')
+  return lines.join('\n')
+}
+
+export function describeStatus (st) {
+  const lines = []
+  if (st.square) lines.push(describeSquareStatus(st.square, { prefix: 'On square ' }))
+  else lines.push(`A read-only checkout of ${st.at ? st.at.slice(0, 12) : 'an empty line'}`)
+  lines.push(`Block: ${st.paths.map((p) => p || '/').join(', ')} at ${st.at ? st.at.slice(0, 12) : '(empty)'}`)
+  if (st.stale) lines.push('The square moved on since this folder last looked: run seam checkout ' + st.square.short + ' after committing.')
+  if (st.conflicted.length) lines.push(`Conflicted (edit and commit without the markers, or seam resolve --ours|--theirs): ${st.conflicted.join(', ')}`)
+  if (!st.changes.length) lines.push('Nothing changed since the last commit.')
+  else lines.push('Changes not yet committed:', ...st.changes.map((c) => `  ${c.status.padEnd(9)} ${c.path}`))
+  return lines.join('\n')
+}
+
+export function describeWrite (r, verb = 'Done') {
+  const c = r.result
+  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(', ')}`)
+  return bits.join('\n')
+}
+
+export function describeMerge (r) {
+  if (r.dry_run) return r.ok ? `Would merge as patch ${r.would_merge.line}:${r.would_merge.patch_no}${r.would_merge.fast ? ' (no file touched on both sides)' : ''}.` : `Would be refused: ${r.refused.detail}.`
+  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(', ')}.`)
+    return lines.join('\n')
+  }
+  const lines = [`Not merged: ${r.refused ? r.refused.detail : r.error}.`]
+  if (r.terms && r.terms.length) {
+    lines.push('Conflicts, now kept in the square:')
+    for (const t of r.terms) lines.push(`  ${t.path} (${t.kind})${t.sides ? `: ${t.sides.map((s) => s.by).join(' vs ')}` : ''}${t.suggestion ? ' (a word-level merge is offered: seam resolve --suggestion, or choose suggestion)' : ''}`)
+    lines.push('Edit those files and commit them without the markers (or seam resolve <path> --ours|--theirs), then merge again.')
+  }
+  return lines.join('\n')
+}
+
+/** Events as one line each (12's inbox line: kind, who, square, paths, patch, would_conflict). */
+export function describeEvents (r) {
+  if (!r.events.length) return `No new events (cursor ${r.after}).`
+  const line = (e) => {
+    const p = e.payload || {}
+    if (e.kind === 'patch.merged') return `#${e.event_seq} patch.merged: patch ${e.patch_no} by ${e.by.member_id} "${first(p.message || '')}" changed ${e.paths.join(', ')} in your square ${e.square_short}${p.would_conflict ? `; would conflict in ${p.would_conflict_paths.join(', ')}` : '; merges cleanly'}`
+    if (e.kind === 'conflict.added') return `#${e.event_seq} conflict.added: ${p.path} (${p.kind}) in ${e.square_short}${p.caused_by && p.caused_by.patch_no ? `, against patch ${p.caused_by.patch_no}` : ''}; settle it and merge again`
+    if (e.kind === 'square.handoff') return `#${e.event_seq} square.handoff: ${e.square_short} from ${p.from} to ${p.to}${p.note ? `: ${p.note}` : ''}`
+    return `#${e.event_seq} ${e.kind}`
+  }
+  return [...r.events.map(line), `(next: after=${r.after})`].join('\n')
+}

package/lib/quilts/export-git.js

@@ -0,0 +1,126 @@
+// The local driver of the one-way git export (plans/quilt-source-control/14, Export): reads a
+// line's patches from the server (GET /quilts/:q/export/git) and writes each as one commit on a
+// branch of a plain git repository with `git fast-import`, so CI and deploys that expect git
+// keep working. The commit fields come from the server whole, so the same patch always gives
+// the same commit id, on any machine, in any number of runs. A run picks up after the last
+// patch it exported (state in the repository's `quilt-export.json`), and refuses a branch that
+// moved under it: the export is one way, never a merge.
+import { spawn, execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const MODES = { file: '100644', exec: '100755', symlink: '120000' }
+const GIT_ENV = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_CONFIG_NOSYSTEM: '1' }
+
+const git = (dir, args) => execFileSync('git', ['-C', dir, ...args], { env: GIT_ENV, maxBuffer: 256 * 1024 * 1024 }).toString().trim()
+const tryGit = (dir, args) => { try { return git(dir, args) } catch { return null } }
+
+/** A path as fast-import reads it: C-quoted when it would otherwise be misread. */
+const fiPath = (p) => (/^"|[\n"\\]/.test(p) ? '"' + p.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"' : p)
+const ident = (who) => `${who.name} <${who.email}> ${who.at} +0000`
+
+/** The repository at `dir`, made bare when it does not exist yet: its git dir. */
+function openRepo (dir) {
+  if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); git(dir, ['init', '-q', '--bare']) }
+  const gd = tryGit(dir, ['rev-parse', '--absolute-git-dir'])
+  if (!gd) throw new Error(`${dir} is not a git repository`)
+  return gd
+}
+
+/** fast-import as a writable stream with backpressure; done() → its exit. */
+function fastImport (dir, marks) {
+  const p = spawn('git', ['-C', dir, 'fast-import', '--quiet', '--date-format=raw', `--export-marks=${marks}`], { env: GIT_ENV, stdio: ['pipe', 'ignore', 'pipe'] })
+  let err = ''
+  p.stderr.on('data', (d) => { err += d })
+  const exit = new Promise((resolve, reject) => p.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`git fast-import failed: ${err.trim()}`)))))
+  exit.catch(() => {})
+  return {
+    write (chunk) { return p.stdin.write(chunk) ? null : new Promise((resolve) => p.stdin.once('drain', resolve)) },
+    async done () { p.stdin.end(); await exit }
+  }
+}
+
+/** Every blob in `ids`, as Buffers, in as many requests as the server's size cap needs. */
+async function fetchBlobs (client, q, ids) {
+  const out = new Map()
+  let todo = [...new Set(ids)]
+  while (todo.length) {
+    const r = await client.blobs(q, todo.slice(0, 2000))
+    const got = Object.entries(r.blobs || {})
+    if (!got.length) throw new Error(`the server returned none of ${todo.length} blobs`)
+    for (const [id, b64] of got) out.set(id, Buffer.from(b64, 'base64'))
+    todo = todo.filter((id) => !out.has(id))
+  }
+  return out
+}
+
+/**
+ * Exports `line` of quilt `q` to `branch` of the repository at `dir` (created bare when
+ * missing). Returns { exported, patch_no, sha, branch }.
+ */
+export async function exportGit (client, { q, dir, line = 'main', branch, page = 200, log = () => {} }) {
+  branch = branch || line
+  const gitDir = openRepo(dir)
+  const stateFile = path.join(gitDir, 'quilt-export.json')
+  const shaFile = path.join(gitDir, 'quilt-export-shas')
+  const all = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : {}
+  const key = `${line}→${branch}`
+  const state = all[key] || null
+  const tip = tryGit(dir, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`])
+  if (state && state.quilt !== undefined && state.quilt !== null) {
+    const info = await client.quilt(q)
+    if (info.id !== state.quilt) throw new Error(`${dir} holds the export of another quilt (${state.quilt})`)
+  }
+  if (state ? tip !== state.sha : tip) throw new Error(`branch ${branch} in ${dir} moved since the last export (${tip || 'gone'}, expected ${state ? state.sha : 'no branch'}): the export never merges or forces; point it at a new branch or repository`)
+
+  let after = state ? state.patch_no : -1
+  let sha = state ? state.sha : null
+  let exported = 0
+  let version = state ? state.version : null
+  let quiltId = state ? state.quilt : null
+  for (;;) {
+    const r = await client.exportPatches(q, { line, after, limit: page })
+    if (version !== null && version !== r.version) throw new Error(`export format ${r.version} differs from the ${version} this branch was exported with: export to a new branch`)
+    version = r.version; quiltId = r.quilt
+    if (!r.patches.length) break
+    const blobs = await fetchBlobs(client, q, r.patches.flatMap((p) => p.changes.filter((c) => c.op === 'put').map((c) => c.blob)))
+    const marksFile = path.join(gitDir, 'quilt-export.marks')
+    const fi = fastImport(dir, marksFile)
+    const send = async (s) => { const w = fi.write(s); if (w) await w }
+    let mark = 0
+    const blobMark = new Map()
+    for (const [id, bytes] of blobs) {
+      blobMark.set(id, ++mark)
+      await send(`blob\nmark :${mark}\ndata ${bytes.length}\n`); await send(bytes); await send('\n')
+    }
+    const commitMark = new Map()
+    let first = true
+    for (const p of r.patches) {
+      commitMark.set(p.patch_no, ++mark)
+      const msg = Buffer.from(p.message, 'utf8')
+      let s = `commit refs/heads/${branch}\nmark :${mark}\nauthor ${ident(p.author)}\ncommitter ${ident(p.committer)}\ndata ${msg.length}\n`
+      await send(s); await send(msg); s = '\n'
+      if (first && sha) s += `from ${sha}\n`
+      first = false
+      for (const c of p.changes) {
+        if (c.op === 'delete') s += `D ${fiPath(c.path)}\n`
+        else s += `M ${MODES[c.mode || 'file'] || MODES.file} :${blobMark.get(c.blob)} ${fiPath(c.path)}\n`
+      }
+      await send(s + '\n')
+    }
+    await fi.done()
+    const marks = new Map(fs.readFileSync(marksFile, 'utf8').split('\n').filter(Boolean).map((l) => { const [m, h] = l.split(' '); return [Number(m.slice(1)), h] }))
+    fs.rmSync(marksFile, { force: true })
+    const lines = r.patches.map((p) => `${line} ${p.patch_no} ${marks.get(commitMark.get(p.patch_no))}`)
+    fs.appendFileSync(shaFile, lines.join('\n') + '\n')
+    const last = r.patches[r.patches.length - 1]
+    after = last.patch_no
+    sha = marks.get(commitMark.get(last.patch_no))
+    exported += r.patches.length
+    all[key] = { quilt: quiltId, line, branch, patch_no: after, sha, version }
+    fs.writeFileSync(stateFile, JSON.stringify(all, null, 2) + '\n')
+    log(`  ${line}/${after} → ${sha.slice(0, 12)} (${exported} exported)`)
+  }
+  if (sha && !tryGit(dir, ['symbolic-ref', '-q', 'HEAD'])?.endsWith(`/${branch}`) && !tryGit(dir, ['rev-parse', '--verify', '-q', 'HEAD'])) git(dir, ['symbolic-ref', 'HEAD', `refs/heads/${branch}`])
+  return { exported, patch_no: after, sha, branch }
+}

package/lib/quilts/hash.js

@@ -0,0 +1,44 @@
+// Ids for Quilt source control (plans/quilt-source-control/03): BLAKE3-256 with a
+// domain-separation context per kind of object, so bytes of one kind can never be presented
+// as another. Ids travel as 64 hex characters.
+import { blake3 } from '@noble/hashes/blake3.js'
+
+const enc = new TextEncoder()
+const contexts = new Map()
+
+/** The context bytes for a kind and format version, e.g. 'commit' → "quilt commit v1". */
+function context (kind) {
+  let c = contexts.get(kind)
+  if (!c) { c = enc.encode(`quilt ${kind} v1`); contexts.set(kind, c) }
+  return c
+}
+
+export const KINDS = ['commit', 'blob', 'tree', 'chunk', 'pack', 'term', 'manifest']
+
+/** The id of `bytes` as an object of `kind`: BLAKE3 derive-key mode, 32 bytes, as hex. */
+// Not object kinds: keys made with their own contexts so they can never equal an object id.
+const KEY_KINDS = ['idempotency']
+
+/** A key (not an object id) in its own context, e.g. 'idempotency' → "quilt idempotency v1". */
+export function keyOf (kind, bytes) {
+  if (!KEY_KINDS.includes(kind)) throw new Error(`unknown key kind ${kind}`)
+  return Buffer.from(blake3(bytes, { context: context(kind) })).toString('hex')
+}
+
+export function idOf (kind, bytes) {
+  if (!KINDS.includes(kind)) throw new Error(`unknown object kind ${kind}`)
+  return Buffer.from(blake3(bytes, { context: context(kind) })).toString('hex')
+}
+
+export const ID = /^[0-9a-f]{64}$/
+
+/** Whether `s` looks like an id (64 lowercase hex). */
+export const isId = (s) => typeof s === 'string' && ID.test(s)
+
+/** An id as its 32 bytes. */
+export const idBytes = (hex) => Buffer.from(hex, 'hex')
+
+/** A quilt's shard (03): blake3 of its id's 16 bytes (plain hash mode), first byte mod 64. */
+export function shardOf (quiltId) {
+  return blake3(Buffer.from(String(quiltId).replace(/-/g, ''), 'hex'))[0] % 64
+}