@heyquilt/seam 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# seam
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command for [Quilt Source](https://frame.heyquilt.com): source control that runs on the
+server, built for many AI agents and people working on one codebase at once. Git's verbs keep
+git's names.
+
+```sh
+npm install -g @heyquilt/seam
+seam login
+seam import git ./my-app
+seam square open "Fix sign-in" --quilt my-app --dir work
+cd work && seam commit -m "Sign-in keeps the session" && seam merge
+seam log --quilt my-app --oneline
+```
+
+A **quilt** is a repository, a **square** is one agent's or task's work in progress, a **patch**
+is a square once it is merged into `main`, and a **block** is the part of a quilt you check out
+on disk (a folder with `.seam/block.json`).
+
+- `seam help` lists every command.
+- `seam mcp` serves the same commands as MCP tools (`seam_log`, `seam_commit`, `seam_merge`, …)
+  for your AI tool.
+- Agents set `SEAM_TOKEN` to their key instead of signing in. `SEAM_API_URL` points at another
+  server.
+
+The docs are at https://frame.heyquilt.com/docs.

package/bin/seam.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// seam: Quilt Source's command (frame.heyquilt.com). Git's verbs for source control that runs on
+// the server; its own package and sign-in, apart from the Quilt app's `quilt` command.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { readAccount, login, logout, resume } from '../lib/account.js'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+// The published package ships the client in lib/quilts (scripts/build.mjs); in the repo it is
+// read straight from the server's src/quilts.
+const QUILTS = fs.existsSync(path.join(here, '../lib/quilts/cli.js')) ? '../lib/quilts' : '../../src/quilts'
+const quilts = (file) => import(`${QUILTS}/${file}`)
+const { version } = JSON.parse(fs.readFileSync(path.join(here, '../package.json'), 'utf8'))
+
+const HELP = `seam ${version}: Quilt Source, source control for people and their agents
+Docs: https://frame.heyquilt.com/docs
+
+  seam login [--no-browser]          Sign in with your heyquilt.com account
+  seam logout | seam whoami
+  seam quilts [new <slug> | show <q>]  Your quilts (repositories)
+  seam import git <path> [--into <slug>]
+  seam square open "<title>" --quilt <q> [--dir <folder>]
+  seam checkout <sq:id | revision> --quilt <q> [--dir <folder>] [-- paths]
+  seam status | diff | commit -m "<message>"   in a block folder
+  seam merge [sq:id] [--into main]   seam rebase | revert <patch:n> | cherry-pick <rev>
+  seam resolve <path>... --ours | --theirs | --base | --side n | --delete
+  seam log [rev] [-n 20] [--oneline]  seam show <rev>  seam blame <path>[@rev]  seam cat | ls
+  seam events [--webhook <url>]      What happened to your squares
+  seam export git <dir>              Back to git
+  seam mcp                           The same commands as MCP tools, for your AI tool
+
+Agents: set SEAM_TOKEN to the agent's key instead of signing in.`
+
+const cmd = process.argv[2]
+const argv = process.argv.slice(3)
+const fail = (msg) => { console.error(msg); process.exit(1) }
+const openBrowser = (url) => { try { spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open', [url], { stdio: 'ignore', detached: true }).unref() } catch {} }
+
+async function main () {
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return console.log(HELP)
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') return console.log(version)
+  if (cmd === 'login') {
+    const a = readAccount()
+    if (a) return console.log(`Already signed in as ${a.account.name} (${a.account.email}). Run seam logout first to switch accounts.`)
+    const r = await login({ open: argv.includes('--no-browser') ? () => {} : openBrowser })
+    return console.log(`Signed in as ${r.account.name} (${r.account.email}).`)
+  }
+  if (cmd === 'logout') { const a = await logout(); return console.log(a ? `Signed out of ${a.account.email}.` : 'Not signed in.') }
+  if (cmd === 'whoami') { const a = readAccount(); if (!a) { process.exitCode = 1; return console.log('Not signed in.') } return console.log(`${a.account.name} (${a.account.email})`) }
+  if (cmd === 'mcp') return mcp()
+  const { SEAM_VERBS, runSeamCommand } = await quilts('cli.js')
+  if (!SEAM_VERBS.has(cmd)) fail(`seam: '${cmd}' is not a seam command. See seam help.`)
+  try {
+    return await runSeamCommand(cmd, argv, { token: readAccount()?.token })
+  } catch (err) {
+    // A lapsed sign-in: renew it with this computer's key and try once more.
+    if (err.status === 401 && !process.env.SEAM_TOKEN && readAccount()) {
+      const back = await resume().catch(() => null)
+      if (back) return runSeamCommand(cmd, argv, { token: back.token })
+      fail('Your sign-in has ended. Run seam login.')
+    }
+    throw err
+  }
+}
+
+// `seam mcp`: the source-control tools for an AI tool, over stdio, as the signed-in person (or SEAM_TOKEN).
+async function mcp () {
+  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js')
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js')
+  const { SEAM_GUIDE, registerSeamTools } = await quilts('tools.js')
+  const { connect } = await quilts('cli.js')
+  const { findBlock } = await quilts('block.js')
+  const server = new McpServer({ name: 'seam', version }, { instructions: SEAM_GUIDE })
+  registerSeamTools(server, { client: () => connect(findBlock()?.block, readAccount()?.token).client, found: () => findBlock() })
+  await server.connect(new StdioServerTransport())
+}
+
+main().catch((err) => fail(err.message))

package/lib/account.js

@@ -0,0 +1,120 @@
+// seam's own sign-in, kept apart from the Quilt app's: an Ed25519 key for this computer in
+// ~/.seam/identity.json and the account token in ~/.seam/account.json (both private, 0600). It
+// signs in to the same heyquilt.com account through the API's device links: `seam login` shows a
+// page to approve, and later a lapsed token is renewed with the key, no browser.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+export const API_URL = 'https://api.heyquilt.com'
+export const apiUrl = () => String(process.env.SEAM_API_URL || API_URL).replace(/\/+$/, '')
+export const seamHome = () => process.env.SEAM_HOME || path.join(os.homedir(), '.seam')
+const accountFile = () => path.join(seamHome(), 'account.json')
+const identityFile = () => path.join(seamHome(), 'identity.json')
+const signedOutFile = () => path.join(seamHome(), 'signed-out')
+
+// The API's signing contexts for linking a computer and signing it back in (src/identity.js).
+const DEVICE_LINK_CONTEXT = 'quilt-device-link-v1'
+const DEVICE_RESUME_CONTEXT = 'quilt-device-resume-v1'
+
+function writePrivate (file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error(`Refusing to write ${file}: it's a symlink`)
+  const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600, flag: 'wx' })
+  fs.renameSync(tmp, file)
+}
+
+/** This computer's key, made on first use. */
+export function loadIdentity () {
+  try {
+    const id = JSON.parse(fs.readFileSync(identityFile(), 'utf8'))
+    if (id.publicKey && id.privateKey) return id
+  } catch {}
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519')
+  const id = { publicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64url') }
+  writePrivate(identityFile(), id)
+  return id
+}
+
+const sign = (identity, text) => crypto.sign(null, Buffer.from(text), crypto.createPrivateKey({ key: Buffer.from(identity.privateKey, 'base64url'), format: 'der', type: 'pkcs8' })).toString('base64url')
+
+/** { token, account: { id, name, email } }, or null when signed out. */
+export function readAccount () {
+  try {
+    const a = JSON.parse(fs.readFileSync(accountFile(), 'utf8'))
+    return a && typeof a.token === 'string' && a.account ? a : null
+  } catch {
+    return null
+  }
+}
+
+function saveAccount (token, profile) {
+  const data = { token, account: { id: profile?.id, name: profile?.name || '', email: profile?.email || '' }, signedInAt: Date.now() }
+  writePrivate(accountFile(), data)
+  fs.rmSync(signedOutFile(), { force: true })
+  return data
+}
+
+async function call (method, route, body, token, extra = {}) {
+  let res
+  try {
+    res = await fetch(apiUrl() + route, { method, headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) }, body: body ? JSON.stringify(body) : undefined, ...extra })
+  } catch (err) {
+    throw new Error(`Couldn't reach Quilt (${err.cause?.code || err.message}).`)
+  }
+  const data = await res.json().catch(() => null)
+  if (!res.ok) throw Object.assign(new Error(data?.error || `Quilt answered ${res.status}.`), { status: res.status })
+  return data || {}
+}
+
+/** Signs this computer back in with its key, no browser; null when it isn't linked (or was signed out on purpose, unless `asked`). */
+export async function resume ({ asked = false } = {}) {
+  if (!asked && fs.existsSync(signedOutFile())) return null
+  const identity = loadIdentity()
+  const at = Date.now()
+  let r
+  try {
+    r = await call('POST', '/v1/device/resume', { publicKey: identity.publicKey, at, signature: sign(identity, `${DEVICE_RESUME_CONTEXT}\0${at}`) })
+  } catch (err) {
+    if ([400, 401, 404].includes(err.status)) return null
+    throw err
+  }
+  return typeof r.token === 'string' ? saveAccount(r.token, r.profile) : null
+}
+
+/** `seam login`: back in with the key if this computer was linked before, else a page to approve in the browser. */
+export async function login ({ say = console.log, open = () => {} } = {}) {
+  const back = await resume({ asked: true }).catch(() => null)
+  if (back) return back
+  const identity = loadIdentity()
+  const link = await call('POST', '/v1/device/start', { publicKey: identity.publicKey, deviceName: `${os.hostname().replace(/\.local$/, '')} (seam)`, platform: process.platform })
+  say(`To sign in, open this page and approve this computer:\n\n  ${link.verificationUrl}\n\nCheck it shows the code ${link.userCode}. Waiting…`)
+  open(link.verificationUrl)
+  const until = Date.now() + link.expiresIn * 1000
+  while (Date.now() < until) {
+    await new Promise((resolve) => setTimeout(resolve, link.interval * 1000))
+    let r
+    try {
+      r = await call('POST', '/v1/device/poll', { deviceCode: link.deviceCode, signature: sign(identity, `${DEVICE_LINK_CONTEXT}\0${link.deviceCode}`) })
+    } catch (err) {
+      if (err.status === 410) break
+      if (err.status === 403) throw new Error('Sign-in was declined in the browser.')
+      if (err.status && !(err.status >= 500 || err.status === 429)) throw err
+      continue
+    }
+    if (r.status === 'approved') return saveAccount(r.token, r.profile)
+  }
+  throw new Error('The code expired. Run seam login again.')
+}
+
+/** `seam logout`: forgets the sign-in here, then revokes it (best effort). */
+export async function logout () {
+  const a = readAccount()
+  fs.rmSync(accountFile(), { force: true })
+  fs.mkdirSync(seamHome(), { recursive: true })
+  fs.writeFileSync(signedOutFile(), '')
+  if (a) await call('POST', '/v1/me/signout', {}, a.token, { signal: AbortSignal.timeout(5000) }).catch(() => {})
+  return a
+}

package/lib/quilts/block.js

@@ -0,0 +1,228 @@
+// Blocks on disk (plans/quilt-source-control/05): a folder holding part of one square, the
+// subtrees named by `paths`, as of commit `at`. The folder is a projection of a known commit
+// plus the edits made in it since; it is rebuilt from the server, never repaired. Its record is
+// .seam/block.json: the quilt, the square, the paths, `at`, the head it last saw, and a
+// manifest of what was written (blob, mode, size, mtime) so status needs no server call.
+import fs from 'node:fs'
+import path from 'node:path'
+import ignore from 'ignore'
+import { blobId, cleanPrefix, under, cmpPath, cleanCommit, commitBytes, commitId } from './records.js'
+import { unified, isText } from './textdiff.js'
+
+/** A block folder's own folder (seam's, not the Quilt app's .quilt). */
+export const BLOCK_DIR = '.seam'
+export const BLOCK_FILE = path.join(BLOCK_DIR, 'block.json')
+const ALWAYS_IGNORED = ['.git', BLOCK_DIR, 'node_modules']
+
+/** The block a folder (or one of its parents) holds, as { dir, block }, or null. */
+export function findBlock (start = process.cwd()) {
+  let dir = path.resolve(start)
+  for (;;) {
+    const f = path.join(dir, BLOCK_FILE)
+    if (fs.existsSync(f)) return { dir, block: JSON.parse(fs.readFileSync(f, 'utf8')) }
+    const up = path.dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+export function saveBlock (dir, block) {
+  fs.mkdirSync(path.join(dir, BLOCK_DIR), { recursive: true })
+  const f = path.join(dir, BLOCK_FILE)
+  fs.writeFileSync(f + '.tmp', JSON.stringify(block, null, 1))
+  fs.renameSync(f + '.tmp', f)
+}
+
+const inBlock = (block, p) => block.paths.some((x) => under(p, x))
+
+function ignorer (dir) {
+  const ig = ignore().add(ALWAYS_IGNORED)
+  try { ig.add(fs.readFileSync(path.join(dir, '.gitignore'), 'utf8')) } catch {}
+  return ig
+}
+
+/** Every file under the block's paths on disk: Map path → { abs, stat }. */
+function scan (dir, block) {
+  const ig = ignorer(dir)
+  const out = new Map()
+  const walk = (rel) => {
+    let names
+    try { names = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }) } catch { return }
+    for (const d of names) {
+      const r = rel ? `${rel}/${d.name}` : d.name
+      if (ig.ignores(d.isDirectory() ? r + '/' : r)) continue
+      if (d.isDirectory()) { if (block.paths.some((x) => under(r, x) || under(x, r))) walk(r); continue }
+      if (!(d.isFile() || d.isSymbolicLink()) || !inBlock(block, r)) continue
+      const abs = path.join(dir, r)
+      out.set(r.normalize('NFC'), { abs, stat: fs.lstatSync(abs) })
+    }
+  }
+  walk('')
+  return out
+}
+
+function readFileEntry (abs, stat) {
+  if (stat.isSymbolicLink()) return { bytes: Buffer.from(fs.readlinkSync(abs)), mode: 'symlink' }
+  return { bytes: fs.readFileSync(abs), mode: (stat.mode & 0o111) && process.platform !== 'win32' ? 'exec' : 'file' }
+}
+
+/**
+ * What changed in the folder since `at`: [{ path, status: 'added' | 'modified' | 'deleted',
+ * blob?, mode?, bytes? }]. A conflicted file still carrying its term's marker is unchanged.
+ */
+export function localChanges (dir, block, { paths = [] } = {}) {
+  const only = paths.map((p) => cleanPrefix(path.relative(dir, path.resolve(p)).split(path.sep).join('/')))
+  const wanted = (p) => !only.length || only.some((x) => under(p, x))
+  const files = scan(dir, block)
+  const out = []
+  for (const [p, { abs, stat }] of files) {
+    if (!wanted(p)) continue
+    const known = block.files[p]
+    if (known && known.size === stat.size && known.mtimeMs === stat.mtimeMs) continue
+    const { bytes, mode } = readFileEntry(abs, stat)
+    const id = blobId(bytes)
+    if (known && known.blob === id && known.mode === mode) continue
+    if (known && known.term && bytes.includes(Buffer.from(`quilt-conflict ${known.term.slice(0, 12)}`))) continue
+    out.push({ path: p, status: known ? 'modified' : 'added', blob: id, mode, size: bytes.length, bytes })
+  }
+  for (const p of Object.keys(block.files)) if (!files.has(p) && wanted(p)) out.push({ path: p, status: 'deleted' })
+  return out.sort((a, b) => cmpPath(a.path, b.path))
+}
+
+/** Writes one tree entry to the folder and returns its manifest record. */
+async function writeEntry (dir, e, content) {
+  const abs = path.join(dir, ...e.path.split('/'))
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  try { fs.rmSync(abs, { force: true }) } catch {}
+  if (e.mode === 'symlink') fs.symlinkSync(content.toString('utf8'), abs)
+  else fs.writeFileSync(abs, content, { mode: e.mode === 'exec' ? 0o755 : 0o644 })
+  const st = fs.lstatSync(abs)
+  return { blob: e.mode === 'conflict' ? null : e.blob, mode: e.mode, size: st.size, mtimeMs: st.mtimeMs, ...(e.term ? { term: e.term } : {}) }
+}
+
+/** Fetches blobs by id in batches (want-only, decision 31). */
+async function fetchBlobs (client, quilt, ids) {
+  const out = new Map()
+  const list = [...new Set(ids)]
+  for (let i = 0; i < list.length; i += 200) {
+    const { blobs } = await client.blobs(quilt, list.slice(i, i + 200))
+    for (const [id, b64] of Object.entries(blobs)) out.set(id, Buffer.from(b64, 'base64'))
+  }
+  return out
+}
+
+async function contentsFor (client, quilt, rev, entries) {
+  const blobs = await fetchBlobs(client, quilt, entries.filter((e) => e.blob).map((e) => e.blob))
+  const get = async (e) => {
+    if (e.mode !== 'conflict') return blobs.get(e.blob)
+    const r = await client.cat(quilt, rev, e.path, { format: 'diff' })
+    return Buffer.from(r.content, 'base64')
+  }
+  return get
+}
+
+/**
+ * Checks out `rev` (a square's head, or any revision) under `paths` into `dir` as a new block.
+ * Refuses a folder that already holds files, unless it is this block's own folder.
+ */
+export async function checkout (client, { quilt, square = null, rev, paths = [''], dir, api }) {
+  const prefixes = (paths.length ? paths : ['']).map(cleanPrefix)
+  fs.mkdirSync(dir, { recursive: true })
+  const existing = fs.readdirSync(dir).filter((n) => n !== BLOCK_DIR)
+  if (existing.length) throw new Error(`${dir} is not empty; check out into an empty folder (or switch an existing block with quilt checkout inside it)`)
+  const sq = square ? await client.square(quilt, square) : null
+  const at = sq ? (sq.head || sq.base) : rev || 'main'
+  const t = await client.tree(quilt, at || 'main', prefixes)
+  const get = await contentsFor(client, quilt, at || 'main', t.entries)
+  const files = {}
+  for (const e of t.entries) files[e.path] = await writeEntry(dir, e, await get(e))
+  const block = { api, quilt, square: sq ? sq.id : null, square_short: sq ? sq.short : null, line: sq ? sq.line : (rev || 'main'), paths: prefixes, at: t.commit, head: sq ? sq.head : null, files }
+  saveBlock(dir, block)
+  return { block, files: t.entries.length }
+}
+
+/**
+ * Moves the folder from `block.at` to commit `to`, file by file: paths changed on the server
+ * are rewritten; a path changed both here and there is left as it is here and reported.
+ */
+export async function syncTo (client, dir, block, to, { square } = {}) {
+  const local = new Map(localChanges(dir, block).map((c) => [c.path, c]))
+  const d = await client.diff(block.quilt, { from: block.at ? `c:${block.at}` : undefined, to: to ? `c:${to}` : 'main', paths: block.paths, format: 'names' })
+  const t = d.files.length ? await client.tree(block.quilt, to ? `c:${to}` : 'main', block.paths) : { entries: [] }
+  const byPath = new Map(t.entries.map((e) => [e.path, e]))
+  const get = await contentsFor(client, block.quilt, to ? `c:${to}` : 'main', d.files.map((f) => byPath.get(f.path)).filter(Boolean))
+  const kept = []
+  let written = 0
+  for (const f of d.files) {
+    if (local.has(f.path)) { kept.push(f.path); continue }
+    const e = byPath.get(f.path)
+    if (!e) { fs.rmSync(path.join(dir, ...f.path.split('/')), { force: true }); delete block.files[f.path]; written++; continue }
+    block.files[f.path] = await writeEntry(dir, e, await get(e))
+    written++
+  }
+  block.at = to
+  if (square) { block.square = square.id; block.square_short = square.short; block.head = square.head; block.line = square.line }
+  saveBlock(dir, block)
+  return { written, kept }
+}
+
+/** status: the folder's changes, and the square as the server sees it. */
+export async function status (client, dir, block) {
+  const changes = localChanges(dir, block).map(({ bytes, ...c }) => c)
+  const square = block.square ? await client.square(block.quilt, block.square) : null
+  const conflicted = Object.entries(block.files).filter(([, f]) => f.term).map(([p]) => p)
+  return { dir, quilt: block.quilt, square, paths: block.paths, at: block.at, changes, conflicted, stale: !!(square && square.head !== block.head) }
+}
+
+/** commit: uploads the changed files' blobs (have?, then a pack) and seals them as a commit. */
+export async function commitFolder (client, dir, block, { message, paths = [] }) {
+  if (!block.square) throw new Error('This folder is a read-only checkout of a line; open a square (quilt square open) to commit.')
+  const changes = localChanges(dir, block, { paths })
+  if (!changes.length) return { nothing: true }
+  const blobs = changes.filter((c) => c.bytes).map((c) => ({ kind: 'blob', id: c.blob, bytes: c.bytes }))
+  const list = changes.map((c) => c.status === 'deleted' ? { path: c.path, op: 'delete' } : { path: c.path, op: 'put', blob: c.blob, mode: c.mode })
+  // 03: the commit record is built here and travels in the pack with its blobs, so the commit
+  // request names it by id. The server refuses a record that is not exactly what it would write
+  // (a file that still carries a conflict's markers, say); then the changes go as a list.
+  let r
+  try {
+    if (!block.author || !block.quilt_id) { const info = await client.quilt(block.quilt); block.author = info.you; block.quilt_id = info.id }
+    const sq = await client.square(block.quilt, block.square)
+    const { on_behalf_of: onBehalf, ...author } = block.author
+    const record = cleanCommit({
+      quilt_id: block.quilt_id, square_id: sq.id, parents: [block.head || sq.base].filter(Boolean), author,
+      ...(onBehalf ? { on_behalf_of: onBehalf } : {}), ...(sq.task_id ? { task_id: sq.task_id } : {}),
+      message: message || '', authored_at: Date.now(),
+      changes: list.map((c) => c.op === 'delete' ? c : { ...c, mode: c.mode || 'file', size: changes.find((x) => x.path === c.path).bytes.length })
+    })
+    const id = commitId(record)
+    await client.upload(block.quilt, [...blobs, { kind: 'commit', id, bytes: commitBytes(record) }])
+    r = await client.commit(block.quilt, block.square, { expect_head: block.head, commit: id })
+  } catch (err) {
+    if (err.code !== 'record_mismatch') throw err
+    r = await client.commit(block.quilt, block.square, { expect_head: block.head, message, changes: list })
+  }
+  for (const c of changes) {
+    if (c.status === 'deleted') { delete block.files[c.path]; continue }
+    const st = fs.lstatSync(path.join(dir, ...c.path.split('/')))
+    block.files[c.path] = { blob: c.blob, mode: c.mode, size: st.size, mtimeMs: st.mtimeMs }
+  }
+  block.at = r.square.head
+  block.head = r.square.head
+  saveBlock(dir, block)
+  return r
+}
+
+/** The folder's changes as a unified diff against `at` (diff with no revision, in a block). */
+export async function localDiff (client, dir, block, { paths = [] } = {}) {
+  const changes = localChanges(dir, block, { paths })
+  const olds = await fetchBlobs(client, block.quilt, changes.map((c) => block.files[c.path]?.blob).filter(Boolean))
+  const out = []
+  for (const c of changes) {
+    const before = block.files[c.path]?.blob ? olds.get(block.files[c.path].blob) : null
+    const after = c.bytes || null
+    if (!isText(before) || !isText(after)) { out.push(`Binary file ${c.path} ${c.status}\n`); continue }
+    out.push(unified(c.path, before ? before.toString('utf8') : null, after ? after.toString('utf8') : null))
+  }
+  return { changes: changes.map(({ bytes, ...c }) => c), text: out.join('') }
+}

package/lib/quilts/cbor.js

@@ -0,0 +1,92 @@
+// Deterministic CBOR (RFC 8949 §4.2.1, "core deterministic encoding") for Quilt records: every
+// id is a hash of these bytes, so every client and server must write exactly the same ones.
+// Supported: unsigned and negative integers (safe range), byte strings (Uint8Array/Buffer),
+// text, arrays, maps (plain objects; keys sorted bytewise on their encoded form), true, false,
+// null. No floats, no indefinite lengths. Undefined fields are left out, never encoded.
+
+function head (major, n) {
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error(`cbor: bad length or integer ${n}`)
+  if (n < 24) return Buffer.from([(major << 5) | n])
+  if (n < 0x100) return Buffer.from([(major << 5) | 24, n])
+  if (n < 0x10000) { const b = Buffer.alloc(3); b[0] = (major << 5) | 25; b.writeUInt16BE(n, 1); return b }
+  if (n < 0x100000000) { const b = Buffer.alloc(5); b[0] = (major << 5) | 26; b.writeUInt32BE(n, 1); return b }
+  const b = Buffer.alloc(9); b[0] = (major << 5) | 27; b.writeBigUInt64BE(BigInt(n), 1); return b
+}
+
+function encodeInto (v, out) {
+  if (v === null) return out.push(Buffer.from([0xf6]))
+  if (v === true) return out.push(Buffer.from([0xf5]))
+  if (v === false) return out.push(Buffer.from([0xf4]))
+  if (typeof v === 'number') {
+    if (!Number.isSafeInteger(v)) throw new Error(`cbor: no floats (${v})`)
+    return out.push(v >= 0 ? head(0, v) : head(1, -1 - v))
+  }
+  if (typeof v === 'string') {
+    const b = Buffer.from(v, 'utf8')
+    out.push(head(3, b.length)); return out.push(b)
+  }
+  if (v instanceof Uint8Array) { out.push(head(2, v.length)); return out.push(Buffer.from(v)) }
+  if (Array.isArray(v)) {
+    out.push(head(4, v.length))
+    for (const x of v) {
+      if (x === undefined) throw new Error('cbor: undefined in an array')
+      encodeInto(x, out)
+    }
+    return
+  }
+  if (typeof v === 'object') {
+    const entries = Object.entries(v).filter(([, x]) => x !== undefined)
+      .map(([k, x]) => [encode(k), x])
+      .sort(([a], [b]) => Buffer.compare(a, b))
+    out.push(head(5, entries.length))
+    for (const [k, x] of entries) { out.push(k); encodeInto(x, out) }
+    return
+  }
+  throw new Error(`cbor: cannot encode ${typeof v}`)
+}
+
+/** The deterministic CBOR bytes of `v`. */
+export function encode (v) {
+  const out = []
+  encodeInto(v, out)
+  return Buffer.concat(out)
+}
+
+/** Decodes one CBOR item (as written by encode); byte strings come back as Buffers. */
+export function decode (buf) {
+  const b = Buffer.from(buf.buffer ? buf : Buffer.from(buf))
+  let pos = 0
+  const arg = (info) => {
+    if (info < 24) return info
+    if (info === 24) return b[pos++]
+    if (info === 25) { const n = b.readUInt16BE(pos); pos += 2; return n }
+    if (info === 26) { const n = b.readUInt32BE(pos); pos += 4; return n }
+    if (info === 27) { const n = Number(b.readBigUInt64BE(pos)); pos += 8; return n }
+    throw new Error('cbor: indefinite or reserved length')
+  }
+  const item = () => {
+    if (pos >= b.length) throw new Error('cbor: truncated')
+    const ib = b[pos++]
+    const major = ib >> 5
+    const info = ib & 31
+    if (major === 7) {
+      if (info === 20) return false
+      if (info === 21) return true
+      if (info === 22) return null
+      throw new Error('cbor: unsupported simple value or float')
+    }
+    const n = arg(info)
+    switch (major) {
+      case 0: return n
+      case 1: return -1 - n
+      case 2: { const v = b.subarray(pos, pos + n); pos += n; if (v.length !== n) throw new Error('cbor: truncated'); return Buffer.from(v) }
+      case 3: { const v = b.toString('utf8', pos, pos + n); pos += n; if (pos > b.length) throw new Error('cbor: truncated'); return v }
+      case 4: { const a = []; for (let i = 0; i < n; i++) a.push(item()); return a }
+      case 5: { const o = {}; for (let i = 0; i < n; i++) { const k = item(); o[k] = item() } return o }
+      default: throw new Error(`cbor: unsupported major type ${major}`)
+    }
+  }
+  const v = item()
+  if (pos !== b.length) throw new Error('cbor: trailing bytes')
+  return v
+}