@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/local/local-sync-plan.ts

@@ -0,0 +1,717 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import type { Portability } from './local-portability'
+import { conflictsId, deepEqual, mergeItemFiles, type Choice, type Side } from './local-sync-merge'
+import { itemTitle } from './local-sync-names'
+import { toNames, type Directory, type Unresolved } from './local-sync-refs'
+import { comparableText, isPluginFile, withLocalSecrets } from './local-secrets'
+
+/**
+ * A pull is a plan first. Each item in the workspace (an Agent with its
+ * behavior settings, a workflow, an object type…) becomes the files the
+ * project would hold; the plan compares them with what the last pull wrote
+ * (`frontera.lock`) and with what is in the folder now, and says per item
+ * whether pulling it is new, a plain update, or would discard local edits.
+ * Only what the person selects is written.
+ */
+
+/**
+ * `dataset` is declared and never read from a workspace: a dataset's rows are
+ * the workspace's records (design §8), so `datasets/` is the project's own
+ * (sample data from `frontera local data`, or files written by hand) and no
+ * pull produces a `dataset/` item. It stays a kind so `--kinds datasets`, a
+ * lock written with one and the change-request kinds keep reading as before.
+ *
+ * `lessons` is an Agent's `lessons.yaml` as a change request carries it
+ * (`lessons/<slug>`): brought by `pull --lessons`, never listed by a fetch or
+ * kept in the lock, and proposed back as rules for the platform's reviewers.
+ */
+export const SYNC_KINDS = ['blueprint', 'dataset', 'skill', 'function', 'plugin', 'knowledge', 'workflow', 'agent', 'evaluation', 'theme', 'chat-app', 'app', 'brand', 'library', 'lessons'] as const
+export type SyncKind = (typeof SYNC_KINDS)[number]
+
+export const KIND_LABEL: Record<SyncKind, string> = {
+  blueprint: 'Blueprint',
+  dataset: 'Datasets',
+  skill: 'Skills',
+  function: 'Functions',
+  plugin: 'Plugins',
+  knowledge: 'Knowledge',
+  workflow: 'Workflows',
+  agent: 'Agents',
+  evaluation: 'Evaluations',
+  theme: 'Slide themes',
+  'chat-app': 'Chat Apps',
+  app: 'Apps',
+  brand: 'Brand',
+  library: 'Library',
+  lessons: 'Lessons',
+}
+
+/** One workspace item as the project would hold it. */
+export interface RemoteItem {
+  /** `agent/support-concierge`: the item's kind and name. */
+  ref: string
+  kind: SyncKind
+  name: string
+  /** What people call it: the display name, beside the name it is filed under. */
+  title: string
+  /** Project-relative path → content. */
+  files: Record<string, string>
+  /** The workspace's version of it, when it has one (a workflow's live version number). */
+  version?: string
+  /** The platform's id for it: survives a rename. */
+  id?: string
+  /** The platform's revision of it, from the sync index; opaque. */
+  revision?: string
+  /** References the pull could not name; the item is pulled with them only once confirmed. */
+  unresolved: Unresolved[]
+  /** What the project's shape cannot hold, said rather than dropped. */
+  notes: string[]
+  /** The other items it names (`function/refund-eligibility`), so a pull can bring them too. */
+  requires?: string[]
+  /** Whether it runs on the local runtime, and how (design §8): computed when it is read. */
+  portability?: Portability
+  /** A workflow's or Function's state on the platform: whether the version read is live, and whether it is switched on. */
+  state?: ItemState
+  /**
+   * Binary files that come with it (a skill's images, fonts, templates), kept
+   * apart from `files`: they are not merged or tracked. A pull writes each one
+   * the project does not have yet and never overwrites one. `bytes` while it
+   * is being read; `from`, the snapshot's copy, once fetched.
+   */
+  assets?: ItemAsset[]
+}
+
+export interface ItemAsset {
+  path: string
+  bytes?: Uint8Array
+  from?: string
+}
+
+/** Write the assets the project does not have yet; never one already there. Returns the paths written. */
+export function placeAssets(root: string, item: Pick<RemoteItem, 'assets'>): string[] {
+  const out: string[] = []
+  for (const asset of item.assets ?? []) {
+    const full = safePath(root, asset.path)
+    if (existsSync(full)) continue
+    let bytes = asset.bytes
+    if (!bytes && asset.from && existsSync(asset.from)) bytes = new Uint8Array(readFileSync(asset.from))
+    if (!bytes) continue
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, bytes)
+    out.push(asset.path)
+  }
+  return out
+}
+
+/** A workflow's or Function's state on the platform, kept in the lock so `local dev` mirrors it (live, switched on or off). */
+export interface ItemState {
+  live: boolean
+  enabled: boolean
+}
+
+/**
+ * Where an item stands between the base (the last pull, `frontera.lock`), the
+ * working files and the workspace (the fetched snapshot):
+ *
+ *   same            up to date
+ *   changed         incoming: only the workspace moved
+ *   edited          changed here: only the files moved
+ *   conflict        both changed (or a file the last pull did not write is in the way): a pull merges
+ *   unresolved      a pull merged it and left conflicts: the files are ours, `<file>.workspace` theirs
+ *   new             new in the workspace
+ *   deleted-remote  deleted in the workspace; the files are still here
+ *   deleted-local   deleted here; the workspace still has it as pulled
+ *   local-only      only here
+ */
+export type ItemStatus = 'new' | 'changed' | 'same' | 'edited' | 'conflict' | 'unresolved' | 'local-only' | 'deleted-remote' | 'deleted-local'
+
+export interface FileChange {
+  path: string
+  /** Absent in the folder or in the workspace. */
+  local: string | null
+  remote: string | null
+}
+
+export interface PlanItem {
+  ref: string
+  kind: SyncKind
+  name: string
+  title: string
+  status: ItemStatus
+  /** Ticked by default in the checklist. */
+  selected: boolean
+  version?: string
+  files: FileChange[]
+  unresolved: Unresolved[]
+  notes: string[]
+  requires: string[]
+  /** How it runs on the local runtime, from the fetch (design §8): the class and each adaptation in words. */
+  portability?: Pick<Portability, 'class' | 'adaptations'>
+  /** Both changed, or pulled with conflicts: how a three-way merge with the workspace comes out now. */
+  merge?: { conflicts: number }
+  /**
+   * Only the workspace moved, and only by naming what it pointed at by id
+   * (`resourceId: <uuid>` is now `action/queueTelcoNotification`): nothing
+   * changed in the workspace. A pull writes the names.
+   */
+  namesOnly?: boolean
+  /** It was conflicted, and a later workspace change merged cleanly with it: the merge is written. */
+  cleared?: boolean
+}
+
+/** A pull that merged with conflicts, until `resolve` settles it. */
+export interface LockConflict {
+  /** The workspace's item hash and revision the merge was against. */
+  remote: string
+  revision?: string
+  /** Files with a `<file>.workspace` beside them. */
+  files: string[]
+  at: string
+  /** How many conflicts, numbered as `diff` numbers them, when recorded. */
+  count?: number
+  /** The numbered conflicts as one value (`conflictsId`): picks made against another are stale. */
+  id?: string
+}
+
+export interface LockEntry {
+  /** The platform's id for the item (lock v2; absent in a v1 lock). */
+  id?: string
+  /** The platform's revision the base holds (lock v2; absent means unknown). */
+  revision?: string
+  /** Hash of the item's files as the workspace gave them: the base's hash. */
+  remote: string
+  /** Hash of each file as written. */
+  files: Record<string, string>
+  version?: string
+  /** A workflow's state on the platform when it was pulled. */
+  state?: ItemState
+  pulledAt: string
+  /** Pulled with conflicts not yet resolved; the base above is still the last clean pull. */
+  conflict?: LockConflict
+}
+
+/**
+ * `frontera.lock`, committed. Version 2 adds each item's platform id and
+ * revision and keeps every v1 field, so a v1 reader still reads it and a v1
+ * lock reads as v2 with those unknown.
+ */
+export interface SyncLock {
+  version: 1 | 2
+  workspace: string
+  pulledAt?: string
+  items: Record<string, LockEntry>
+}
+
+export const LOCK_FILE = 'frontera.lock'
+
+export function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16)
+}
+
+export function itemHash(files: Record<string, string>): string {
+  return hash(Object.keys(files).sort().map((p) => `${p}\0${files[p]}`).join('\0\0'))
+}
+
+export function readLock(root: string): SyncLock | null {
+  const file = join(root, LOCK_FILE)
+  if (!existsSync(file)) return null
+  try {
+    const lock = JSON.parse(readFileSync(file, 'utf8')) as SyncLock
+    if (!lock || typeof lock !== 'object' || !lock.items || typeof lock.items !== 'object') return null
+    return { ...lock, version: lock.version === 2 ? 2 : 1 }
+  } catch {
+    return null
+  }
+}
+
+/** Sorted keys, two spaces, a final newline: a lock diffs cleanly in review. Always written as v2. */
+export function writeLock(root: string, lock: SyncLock): void {
+  const items = Object.fromEntries(Object.keys(lock.items).sort().map((k) => [k, sortEntry(lock.items[k]!)]))
+  writeFileSync(join(root, LOCK_FILE), `${JSON.stringify({ version: 2, workspace: lock.workspace, ...(lock.pulledAt ? { pulledAt: lock.pulledAt } : {}), items }, null, 2)}\n`)
+}
+
+function sortEntry(entry: LockEntry): LockEntry {
+  return {
+    ...(entry.id ? { id: entry.id } : {}),
+    ...(entry.revision ? { revision: entry.revision } : {}),
+    remote: entry.remote,
+    files: Object.fromEntries(Object.keys(entry.files).sort().map((k) => [k, entry.files[k]!])),
+    ...(entry.version ? { version: entry.version } : {}),
+    ...(entry.state ? { state: entry.state } : {}),
+    pulledAt: entry.pulledAt,
+    ...(entry.conflict ? { conflict: sortConflict(entry.conflict) } : {}),
+  }
+}
+
+function sortConflict(c: LockConflict): LockConflict {
+  return {
+    remote: c.remote,
+    ...(c.revision ? { revision: c.revision } : {}),
+    files: [...c.files].sort(),
+    at: c.at,
+    ...(c.count !== undefined ? { count: c.count } : {}),
+    ...(c.id ? { id: c.id } : {}),
+  }
+}
+
+/** A project-relative path that stays inside the project. */
+export function safePath(root: string, rel: string): string {
+  const full = resolve(root, rel)
+  const back = relative(root, full)
+  if (!back || back.startsWith('..') || back.split(sep).includes('..') || rel.startsWith('/')) throw new Error(`refusing to write outside the project: ${rel}`)
+  return full
+}
+
+export function readLocal(root: string, rel: string): string | null {
+  const full = safePath(root, rel)
+  try {
+    return existsSync(full) ? readFileSync(full, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The status of one item from three hashes (§6 of the sync v2 design): the
+ * base (`remote` in the lock, null when never pulled), the working files
+ * (over the base's paths, null when none of them exist) and the workspace
+ * (null when it does not have the item). `localMatchesRemote` says the files
+ * are exactly the workspace's. `remoteKnownGone`: the workspace's list is
+ * complete for the item's kind, so its absence is a deletion and not a gap.
+ * Null: nothing to show (gone on both sides).
+ */
+export function statusFor(base: string | null, local: string | null, remote: string | null, localMatchesRemote: boolean, remoteKnownGone = false): ItemStatus | null {
+  if (remote !== null && localMatchesRemote) return 'same'
+  if (base === null) {
+    if (remote !== null) return local === null ? 'new' : 'conflict'
+    return local === null ? null : 'local-only'
+  }
+  if (remote === null) {
+    if (local === null) return null
+    return remoteKnownGone ? 'deleted-remote' : 'local-only'
+  }
+  const remoteMoved = remote !== base
+  if (local === null) return remoteMoved ? 'conflict' : 'deleted-local'
+  const localMoved = local !== base
+  if (remoteMoved && localMoved) return 'conflict'
+  if (localMoved) return 'edited'
+  if (remoteMoved) return 'changed'
+  return 'same'
+}
+
+/** A working file as it compares with the workspace's: a Plugin's secret values, this computer's own, left out. */
+function readComparable(root: string, rel: string, base?: (path: string) => string | null): string | null {
+  const text = readLocal(root, rel)
+  return text === null ? null : comparableText(rel, text, isPluginFile(rel) ? (base?.(rel) ?? null) : null)
+}
+
+/** Hash of the working files at these paths, or null when none of them exist. */
+function localHash(root: string, paths: string[], base?: (path: string) => string | null): string | null {
+  const files: Record<string, string> = {}
+  for (const p of paths) {
+    const content = readComparable(root, p, base)
+    if (content !== null) files[p] = content
+  }
+  return Object.keys(files).length ? itemHash(files) : null
+}
+
+export interface PlanOptions {
+  /** Whether the workspace's list is complete for this ref's kind (a fetched snapshot after a full index). */
+  remoteKnownGone?: (ref: string) => boolean
+  /** A base file as the last pull wrote it (`.frontera/sync/base/`), for previewing merges. */
+  base?: (path: string) => string | null
+  /** The workspace's names → ids at the last fetch, so an id and the name it resolves to compare equal. */
+  directory?: Directory
+}
+
+/** The base's files for an item: each as last pulled, or null where it is missing or no longer matches the lock. */
+export function baseFiles(entry: LockEntry | undefined, read: ((path: string) => string | null) | undefined): Record<string, string | null> {
+  const out: Record<string, string | null> = {}
+  for (const [path, wrote] of Object.entries(entry?.files ?? {})) {
+    const content = read?.(path) ?? null
+    out[path] = content !== null && hash(content) === wrote ? content : null
+  }
+  return out
+}
+
+/** The working files at these paths, null where absent. */
+export function localFiles(root: string, paths: string[]): Record<string, string | null> {
+  return Object.fromEntries(paths.map((p) => [p, readLocal(root, p)]))
+}
+
+function parsed(path: string, text: string): { ok: true; value: unknown } | { ok: false } {
+  try {
+    if (/\.json$/i.test(path)) return { ok: true, value: JSON.parse(text) }
+    if (/\.ya?ml$/i.test(path)) return { ok: true, value: parseYaml(text) }
+  } catch {
+    // Not a document: compared as text.
+  }
+  return { ok: false }
+}
+
+/**
+ * Whether two versions of an item's files differ only in naming: each file
+ * is the same document once ids the directory knows are written as names.
+ * Text files must match exactly.
+ */
+export function differsOnlyInNames(local: Record<string, string | null>, remote: Record<string, string>, directory: Directory): boolean {
+  const paths = new Set([...Object.keys(local).filter((p) => local[p] !== null), ...Object.keys(remote)])
+  let differs = false
+  for (const path of paths) {
+    const l = local[path] ?? null
+    const r = remote[path] ?? null
+    if (l === r) continue
+    if (l === null || r === null) return false
+    const a = parsed(path, l)
+    const b = parsed(path, r)
+    if (!a.ok || !b.ok) return false
+    if (!deepEqual(toNames(a.value, directory).doc, toNames(b.value, directory).doc)) return false
+    differs = true
+  }
+  return differs
+}
+
+/**
+ * The plan for each workspace item, plus the items the project holds that
+ * the workspace does not (`localOnly`: refs from the last pull or from the
+ * folder, for information; push is later).
+ */
+/** An Agent's files, as push sends them. */
+const AGENT_FILES = ['agent.json', 'operating.json', 'bindings.json'] as const
+
+export function computePlan(root: string, remote: RemoteItem[], lock: SyncLock | null, localOnly: Array<{ ref: string; kind: SyncKind; name: string; files: string[] }> = [], opts: PlanOptions = {}): PlanItem[] {
+  const plan: PlanItem[] = []
+  const seen = new Set<string>()
+  for (const item of remote) {
+    seen.add(item.ref)
+    const entry = lock?.items[item.ref]
+    const paths = [...new Set([...Object.keys(item.files), ...Object.keys(entry?.files ?? {})])].sort()
+    const files: FileChange[] = paths.map((path) => ({ path, local: readComparable(root, path, opts.base), remote: item.files[path] ?? null }))
+    // An Agent's file that neither the base nor the workspace has but the folder does (its first tools, in a new
+    // `bindings.json`) is a change here too, as push reads it: otherwise status says nothing while push proposes it.
+    const added = item.kind === 'agent' ? AGENT_FILES.map((f) => `agents/${item.name}/${f}`).filter((p) => !paths.includes(p) && existsSync(join(root, p))) : []
+    const matches = files.every((f) => f.local === f.remote) && !added.length
+    // The files as they stand over the base's paths, plus any path only the workspace has that is
+    // already in the folder: a file the pull would overwrite counts as a change here.
+    const basePaths = entry ? [...Object.keys(entry.files), ...files.filter((f) => !(f.path in entry.files) && f.local !== null).map((f) => f.path), ...added] : Object.keys(item.files)
+    const found = statusFor(entry?.remote ?? null, localHash(root, basePaths, opts.base), itemHash(item.files), matches) ?? 'same'
+    // Pulled with conflicts and not resolved: it stays so until `resolve`, whatever the files say.
+    const status: ItemStatus = entry?.conflict && found !== 'same' ? 'unresolved' : found
+    let merge: PlanItem['merge']
+    if (status === 'conflict' || status === 'unresolved') {
+      const local = localFiles(root, paths)
+      merge = { conflicts: mergeItemFiles(baseFiles(entry, opts.base), local, item.files).conflicts }
+    }
+    const namesOnly = status === 'changed' && opts.directory ? differsOnlyInNames(localFiles(root, paths), item.files, opts.directory) : false
+    plan.push({
+      ref: item.ref,
+      kind: item.kind,
+      name: item.name,
+      // As every surface names it; a snapshot read before display names gets them from the files.
+      title: itemTitle(item.kind, item.name, item.files, item.title),
+      status,
+      // What a pull takes without asking: the workspace's changes, and merges that come out clean.
+      selected: status === 'changed' || (status === 'conflict' && merge?.conflicts === 0),
+      version: item.version,
+      files: files.filter((f) => f.local !== f.remote),
+      unresolved: item.unresolved,
+      notes: item.notes,
+      requires: item.requires ?? [],
+      ...(item.portability ? { portability: { class: item.portability.class, adaptations: item.portability.adaptations } } : {}),
+      ...(merge ? { merge } : {}),
+      ...(namesOnly ? { namesOnly } : {}),
+    })
+  }
+  const localRefs = new Map(localOnly.map((l) => [l.ref, l]))
+  for (const ref of Object.keys(lock?.items ?? {})) {
+    if (seen.has(ref) || localRefs.has(ref)) continue
+    const [kind, ...rest] = ref.split('/')
+    if ((SYNC_KINDS as readonly string[]).includes(kind ?? '')) localRefs.set(ref, { ref, kind: kind as SyncKind, name: rest.join('/'), files: Object.keys(lock!.items[ref]!.files) })
+  }
+  for (const l of localRefs.values()) {
+    if (seen.has(l.ref)) continue
+    const entry = lock?.items[l.ref]
+    const local = localHash(root, entry ? Object.keys(entry.files) : l.files)
+    // Something the folder has on its own, never pulled: only here. Pulled once and gone from
+    // the workspace: deleted there, when the workspace's list is known complete.
+    const status = statusFor(entry?.remote ?? null, local, null, false, opts.remoteKnownGone?.(l.ref) ?? false)
+    if (!status) continue
+    // Named as its files name it here, as the workspace would.
+    const own = Object.fromEntries(Object.entries(localFiles(root, l.files)).filter((e): e is [string, string] => e[1] !== null))
+    plan.push({ ref: l.ref, kind: l.kind, name: l.name, title: itemTitle(l.kind, l.name, own), status, selected: false, files: [], unresolved: [], notes: [], requires: [] })
+  }
+  return plan.sort((a, b) => SYNC_KINDS.indexOf(a.kind) - SYNC_KINDS.indexOf(b.kind) || a.title.localeCompare(b.title))
+}
+
+export interface ApplyOptions {
+  /** Items both sides changed: merged three ways from the base instead of written over. */
+  merge?: Set<string>
+  /** A base file as the last pull wrote it. */
+  base?: (path: string) => string | null
+}
+
+export interface ApplyResult {
+  written: string[]
+  removed: string[]
+  lock: SyncLock
+  /** Items merged cleanly. */
+  merged: string[]
+  /** Items merged with conflicts: their files are untouched, and `<file>.workspace` holds the workspace's version. */
+  conflicted: Array<{ ref: string; conflicts: number; files: string[] }>
+}
+
+/** The lock entry for an item as the workspace has it: the base after a pull or a resolve. */
+function entryFor(item: RemoteItem, now: string): LockEntry {
+  return {
+    ...(item.id ? { id: item.id } : {}),
+    ...(item.revision ? { revision: item.revision } : {}),
+    remote: itemHash(item.files),
+    files: Object.fromEntries(Object.entries(item.files).map(([p, c]) => [p, hash(c)])),
+    ...(item.version ? { version: item.version } : {}),
+    ...(item.state ? { state: item.state } : {}),
+    pulledAt: now,
+  }
+}
+
+export const WORKSPACE_SUFFIX = '.workspace'
+
+/** Write or delete a working file; true when it changed. */
+function put(root: string, path: string, content: string | null): boolean {
+  const full = safePath(root, path)
+  const now = readLocal(root, path)
+  if (now === content) return false
+  if (content === null) rmSync(full, { force: true })
+  else {
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+  }
+  return true
+}
+
+/** Remove the folders a deleted file leaves empty, up to the project. */
+function pruneEmpty(root: string, path: string): void {
+  let dir = dirname(safePath(root, path))
+  const top = resolve(root)
+  while (dir !== top && dir.startsWith(`${top}${sep}`)) {
+    try {
+      if (readdirSync(dir).length) return
+      rmdirSync(dir)
+    } catch {
+      return
+    }
+    dir = dirname(dir)
+  }
+}
+
+/** Remove the `<file>.workspace` copies a conflict left beside these files. */
+function clearWorkspaceCopies(root: string, paths: string[]): string[] {
+  const removed: string[] = []
+  for (const path of paths) {
+    const copy = `${path}${WORKSPACE_SUFFIX}`
+    if (existsSync(safePath(root, copy))) {
+      rmSync(safePath(root, copy))
+      removed.push(copy)
+    }
+  }
+  return removed
+}
+
+/**
+ * Write the chosen items' files and record them in the lock. Files the
+ * workspace no longer has for an item (a removed evaluation file) are
+ * deleted only when the last pull wrote them and nobody edited them since.
+ *
+ * An item in `merge` (both sides changed) is merged three ways instead. Clean:
+ * the merged files are written and the base moves to the workspace's
+ * revision. With conflicts nothing of the item is written over: its files
+ * keep the local version, the workspace's version of each conflicted file
+ * goes beside it as `<file>.workspace`, and the lock marks it conflicted.
+ */
+export function applyItems(root: string, workspace: string, items: RemoteItem[], lock: SyncLock | null, opts: ApplyOptions = {}): ApplyResult {
+  const next: SyncLock = { version: 2, workspace, items: { ...(lock?.workspace === workspace ? lock.items : {}) } }
+  const now = new Date().toISOString()
+  const written: string[] = []
+  const removed: string[] = []
+  const merged: string[] = []
+  const conflicted: ApplyResult['conflicted'] = []
+  for (const item of items) {
+    const previous = next.items[item.ref]
+    if (opts.merge?.has(item.ref)) {
+      const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {})])].sort()
+      const result = mergeItemFiles(baseFiles(previous, opts.base), localFiles(root, paths), item.files)
+      if (result.conflicts) {
+        const files = result.files.filter((f) => f.conflicts.length).map((f) => f.path)
+        for (const path of files) {
+          const theirs = item.files[path]
+          // A file the workspace deleted has no copy to put beside it; the conflict says so.
+          if (theirs !== undefined && put(root, `${path}${WORKSPACE_SUFFIX}`, theirs)) written.push(`${path}${WORKSPACE_SUFFIX}`)
+        }
+        next.items[item.ref] = {
+          ...(previous ?? { remote: '', files: {}, pulledAt: now }),
+          conflict: { remote: itemHash(item.files), ...(item.revision ? { revision: item.revision } : {}), files, at: now, count: result.conflicts, id: conflictsId(result.files) },
+        }
+        conflicted.push({ ref: item.ref, conflicts: result.conflicts, files })
+        continue
+      }
+      for (const f of result.files) if (put(root, f.path, f.merged)) (f.merged === null ? removed : written).push(f.path)
+      removed.push(...clearWorkspaceCopies(root, paths))
+      written.push(...placeAssets(root, item))
+      next.items[item.ref] = entryFor(item, now)
+      merged.push(item.ref)
+      continue
+    }
+    for (const [path, remote] of Object.entries(item.files)) {
+      const full = safePath(root, path)
+      mkdirSync(dirname(full), { recursive: true })
+      // A Plugin's secret values set here stay: they are this computer's configuration.
+      const content = isPluginFile(path) ? withLocalSecrets(remote, readLocal(root, path)) : remote
+      if (readLocal(root, path) !== content) {
+        writeFileSync(full, content)
+        written.push(path)
+      }
+    }
+    for (const [path, wroteHash] of Object.entries(previous?.files ?? {})) {
+      if (path in item.files) continue
+      // A file another item still holds stays (a shared file two Functions import).
+      if (Object.entries(next.items).some(([ref, e]) => ref !== item.ref && path in (e.files ?? {}))) continue
+      const local = readLocal(root, path)
+      if (local !== null && hash(local) === wroteHash) {
+        rmSync(safePath(root, path))
+        removed.push(path)
+      }
+    }
+    written.push(...placeAssets(root, item))
+    next.items[item.ref] = entryFor(item, now)
+  }
+  next.pulledAt = now
+  writeLock(root, next)
+  return { written, removed, lock: next, merged, conflicted }
+}
+
+export interface RefreshResult {
+  lock: SyncLock
+  /**
+   * `renumbered`: still conflicted, against the workspace's newer version: the
+   * `.workspace` copies and the conflict record are redone. `cleared`: the
+   * newer version merges cleanly with the files here: the merge is written,
+   * the copies go and the base moves. `unchanged`: nothing to redo.
+   */
+  outcome: 'renumbered' | 'cleared' | 'unchanged'
+  conflicts: number
+  written: string[]
+  removed: string[]
+}
+
+/**
+ * An item pulled with conflicts, when the workspace moved again before it was
+ * resolved: merge the base and the files here with the workspace's newer
+ * version, as the pull did. Conflicts left: the `.workspace` copies are
+ * rewritten from the newer version (a file no longer conflicted loses its
+ * copy) and the lock's conflict record is renumbered. None left: the merged
+ * files are written, the copies removed, and the base becomes the
+ * workspace's revision, as a clean pull leaves it.
+ */
+export function refreshConflict(root: string, workspace: string, item: RemoteItem, lock: SyncLock | null, base?: (path: string) => string | null): RefreshResult {
+  const same = lock?.workspace === workspace
+  const next: SyncLock = { version: 2, workspace, ...(same && lock.pulledAt ? { pulledAt: lock.pulledAt } : {}), items: { ...(same ? lock.items : {}) } }
+  const previous = next.items[item.ref]
+  const remote = itemHash(item.files)
+  if (!previous?.conflict || previous.conflict.remote === remote) return { lock: next, outcome: 'unchanged', conflicts: previous?.conflict?.count ?? 0, written: [], removed: [] }
+  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous.files), ...previous.conflict.files])].sort()
+  const result = mergeItemFiles(baseFiles(previous, base), localFiles(root, paths), item.files)
+  const now = new Date().toISOString()
+  const written: string[] = []
+  const removed: string[] = []
+  if (result.conflicts) {
+    const files = result.files.filter((f) => f.conflicts.length).map((f) => f.path)
+    for (const path of files) {
+      const theirs = item.files[path]
+      if (theirs !== undefined) {
+        if (put(root, `${path}${WORKSPACE_SUFFIX}`, theirs)) written.push(`${path}${WORKSPACE_SUFFIX}`)
+      } else removed.push(...clearWorkspaceCopies(root, [path]))
+    }
+    removed.push(...clearWorkspaceCopies(root, paths.filter((p) => !files.includes(p))))
+    next.items[item.ref] = { ...previous, conflict: { remote, ...(item.revision ? { revision: item.revision } : {}), files, at: now, count: result.conflicts, id: conflictsId(result.files) } }
+    writeLock(root, next)
+    return { lock: next, outcome: 'renumbered', conflicts: result.conflicts, written, removed }
+  }
+  for (const f of result.files) if (put(root, f.path, f.merged)) (f.merged === null ? removed : written).push(f.path)
+  removed.push(...clearWorkspaceCopies(root, paths))
+  next.items[item.ref] = entryFor(item, now)
+  // It finishes the pull that left the conflict.
+  next.pulledAt = now
+  writeLock(root, next)
+  return { lock: next, outcome: 'cleared', conflicts: 0, written, removed }
+}
+
+export type Resolution = { edited: true } | { keep?: Side; picks?: Map<number, Choice> }
+
+/**
+ * Settle an item both sides changed: merge it with a side chosen for each
+ * conflict (`picks` by index, both where a conflict offers it; the rest
+ * `keep`), or take the files as the person edited them (`edited`). The
+ * `.workspace` copies go, and the base becomes the workspace's revision, so
+ * what is left differs only by what was kept from here. Throws when a
+ * conflict has no side, or both is picked for a single value.
+ */
+export function resolveItem(root: string, workspace: string, item: RemoteItem, lock: SyncLock | null, how: Resolution, base?: (path: string) => string | null): { written: string[]; removed: string[]; lock: SyncLock } {
+  const next: SyncLock = { version: 2, workspace, items: { ...(lock?.workspace === workspace ? lock.items : {}) } }
+  const previous = next.items[item.ref]
+  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {}), ...(previous?.conflict?.files ?? [])])].sort()
+  const written: string[] = []
+  const removed: string[] = []
+  if (!('edited' in how)) {
+    const unchosen: number[] = []
+    const result = mergeItemFiles(baseFiles(previous, base), localFiles(root, paths), item.files, {
+      choose: (i) => {
+        const side = how.picks?.get(i) ?? how.keep
+        if (!side) unchosen.push(i)
+        return side
+      },
+    })
+    if (unchosen.length) throw new Error(`no side chosen for conflict${unchosen.length === 1 ? '' : 's'} ${unchosen.join(', ')}`)
+    for (const f of result.files) if (put(root, f.path, f.merged)) (f.merged === null ? removed : written).push(f.path)
+  }
+  removed.push(...clearWorkspaceCopies(root, paths))
+  const now = new Date().toISOString()
+  next.items[item.ref] = entryFor(item, now)
+  next.pulledAt = now
+  writeLock(root, next)
+  return { written, removed, lock: next }
+}
+
+/**
+ * Items the workspace deleted: forget them in the lock, and with
+ * `deleteFiles` delete their files here too; without, they stay as items
+ * only this project has.
+ */
+export function forgetItems(root: string, workspace: string, refs: string[], lock: SyncLock | null, deleteFiles: boolean): { removed: string[]; forgotten: Record<string, string[]>; lock: SyncLock } {
+  const next: SyncLock = { version: 2, workspace, items: { ...(lock?.workspace === workspace ? lock.items : {}) } }
+  const removed: string[] = []
+  const forgotten: Record<string, string[]> = {}
+  for (const ref of refs) {
+    const entry = next.items[ref]
+    if (!entry) continue
+    const paths = Object.keys(entry.files)
+    forgotten[ref] = paths
+    if (deleteFiles) for (const path of paths) if (put(root, path, null)) removed.push(path)
+    removed.push(...clearWorkspaceCopies(root, [...paths, ...(entry.conflict?.files ?? [])]))
+    if (deleteFiles) for (const path of paths) pruneEmpty(root, path)
+    delete next.items[ref]
+  }
+  next.pulledAt = new Date().toISOString()
+  writeLock(root, next)
+  return { removed, forgotten, lock: next }
+}
+
+/** Counts by status, for `sync status` and Forge's card. */
+export function summarize(plan: PlanItem[]): Record<ItemStatus, number> {
+  const out: Record<ItemStatus, number> = { new: 0, changed: 0, same: 0, edited: 0, conflict: 0, unresolved: 0, 'local-only': 0, 'deleted-remote': 0, 'deleted-local': 0 }
+  for (const p of plan) out[p.status]++
+  return out
+}