@frontera-sdk/cli 1.52.28 → 1.52.29

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

@@ -0,0 +1,526 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { CliError } from '../errors'
+import { writeFileAtomic } from '../fs-atomic'
+import { hash, itemHash, safePath, SYNC_KINDS, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
+import { readOrgSettings, type OrgSettings } from './local-org-settings'
+import type { Portability } from './local-portability'
+import { readWorkspace, type SyncSource } from './local-sync-remote'
+import { REF_KINDS, type Directory, type RefKind, type Unresolved } from './local-sync-refs'
+
+/**
+ * The workspace as last fetched, kept beside the project the way git keeps
+ * `refs/remotes/origin`: `frontera local sync fetch` writes it, and status,
+ * the pull plan and Forge's card read it without calling the platform.
+ *
+ *   .frontera/sync/remote.json   cursor, when, the platform's version and capabilities, every item
+ *   .frontera/sync/remote/       the items' files in project form, as a pull would write them
+ *   .frontera/sync/base/         the files each item had when last pulled: the merge base
+ *
+ * None of it is committed (`.frontera/.gitignore`): the snapshot is
+ * re-fetched and the base re-read at the revisions `frontera.lock` records.
+ */
+
+export const SYNC_DIR = join('.frontera', 'sync')
+const REMOTE_JSON = join(SYNC_DIR, 'remote.json')
+const REMOTE_DIR = join(SYNC_DIR, 'remote')
+const BASE_DIR = join(SYNC_DIR, 'base')
+/** Binary files that come with an item (a skill's assets), apart from its text files. */
+const ASSETS_DIR = join(SYNC_DIR, 'remote-assets')
+
+/** Kinds the index lists as one entry, read whole: a project holds them as many files cut from one read. */
+const GROUP_KINDS: readonly SyncKind[] = ['blueprint', 'evaluation', 'brand', 'library']
+
+/** A full index (no cursor) at least this often, so deletions and changes without a timestamp are seen. */
+export const FULL_INDEX_EVERY_MS = 60 * 60 * 1000
+
+export interface SnapshotItem {
+  kind: SyncKind
+  name: string
+  title: string
+  id?: string
+  revision?: string
+  hash: string
+  files: string[]
+  version?: string
+  unresolved: Unresolved[]
+  notes: string[]
+  requires: string[]
+  /** Whether it runs on the local runtime, and how (§8): class, adaptations in words, and what it needs. */
+  portability?: Portability
+  /** A workflow's or Function's state on the platform: live, switched on. */
+  state?: RemoteItem['state']
+  /** Its binary files (a skill's assets), by project path, kept under `.frontera/sync/remote-assets/`. */
+  assets?: string[]
+}
+
+export interface RemoteSnapshot {
+  version: 1
+  workspace: string
+  /** The index's cursor; null after a full read on a platform without the index. */
+  cursor: string | null
+  fetchedAt: string
+  /** When the index was last read whole, so deletions are known as of then. */
+  fullIndexAt: string | null
+  /** The platform has no sync index: every fetch reads the whole workspace. */
+  full: boolean
+  platformVersion: string | null
+  capabilities: string[]
+  /** Kinds the index covers for this key: a ref of one of them missing from the snapshot is deleted. */
+  kinds: SyncKind[]
+  /** Revisions of the kinds read whole (the Blueprint, evaluations). */
+  groups: Partial<Record<SyncKind, string>>
+  /** Items the index lists that hold nothing a project can file (a workflow without a definition), by revision, so they are not read again until they change. */
+  skipped: Record<string, string>
+  items: Record<string, SnapshotItem>
+  /** From the last read of content. */
+  warnings: string[]
+  notes: string[]
+  /**
+   * The workspace's names → ids for each kind a reference may point at, as of
+   * the last read, so the plan can tell a file that only gained names (an id
+   * now written `action/resetLine`) from a change.
+   */
+  names?: Partial<Record<RefKind, Record<string, string>>>
+  /**
+   * Read with an organization key as well: it brings governed Actions (and,
+   * for older platforms, the Blueprint). A snapshot read with other keys is
+   * read again whole, so adding the key brings what it can read.
+   */
+  organizationKey?: boolean
+  /** What this CLI reads of an item (`SNAPSHOT_READER`); absent: 1. */
+  reader?: number
+  /**
+   * The organization's timezone, AI settings and feature flags, read on every
+   * fetch (`/v1/sync/settings`), so `local dev` can take the timezone and say
+   * where the runtime differs. Absent on a platform without the route.
+   */
+  settings?: OrgSettings
+}
+
+/**
+ * Raised when the CLI starts reading more of an item than before, so a
+ * snapshot an older one took is read again whole instead of waiting for each
+ * item's revision to move. 2: an Agent's Context and data (its Blueprint grants).
+ * 3: a Plugin's policy and an Agent's tool settings, an Agent's permission
+ * rules and guardrails, a knowledge base's search settings, and whether a
+ * workflow is live and on. 4: the index's revisions now move when a workflow
+ * is switched on or off and when a Plugin's per-tool policy changes; before,
+ * those changes left the revision as it was, so a snapshot can hold them
+ * stale. 5: a Function never deployed (its editor draft) and its on/off
+ * switch, a Plugin's secret settings as declared empty placeholders, and a
+ * skill's assets. 6: saved object sets, and a workflow's Blueprint step
+ * naming its set (`objectSet/<name>`) instead of the platform's id; a
+ * pulled Agent no longer carries the legacy `functions` rows. 7: evaluation
+ * cases keep their pattern and tool-call checks, judged expectations, gold
+ * flag and scenarios, every item is read, and the regression dataset is
+ * marked. 8: an Agent's Context and data is read with the workspace key where
+ * the platform gives it, and one that can't be read is said
+ * (`blueprintUnread`); a skill's assets are read with the workspace key.
+ * 9: an evaluation case keeps the name a change request recorded for it.
+ * 10: a Plugin's description and icon. 11: Custom Apps, the brand and the
+ * library. 12: an Agent's object tools carry their object definitions,
+ * named by slug (`object/<slug>`). 13: a knowledge base's quality checks
+ * (`quality-checks.yaml`).
+ */
+export const SNAPSHOT_READER = 13
+
+/** The directory the snapshot recorded, as the reference rewriter reads it. */
+export function directoryOf(snap: RemoteSnapshot | null): Directory | undefined {
+  if (!snap?.names) return undefined
+  return Object.fromEntries(Object.entries(snap.names).map(([k, v]) => [k, new Map(Object.entries(v ?? {}))])) as Directory
+}
+
+function namesOf(directory: Directory): RemoteSnapshot['names'] {
+  return Object.fromEntries(REF_KINDS.flatMap((k) => (directory[k] ? [[k, Object.fromEntries([...directory[k]!].sort(([a], [b]) => a.localeCompare(b)))]] : [])))
+}
+
+/**
+ * What the snapshot holds, in one value: every item's ref, revision and
+ * content hash. A preview records it; applying a plan whose snapshot has
+ * moved since (a fetch brought changes) plans again first. A fetch that
+ * brought nothing keeps it, so it is not stale for nothing.
+ */
+export function snapshotId(snap: RemoteSnapshot): string {
+  return hash(Object.keys(snap.items).sort().map((r) => `${r}\0${snap.items[r]!.revision ?? ''}\0${snap.items[r]!.hash}`).join('\n'))
+}
+
+export function readSnapshot(root: string): RemoteSnapshot | null {
+  const file = join(root, REMOTE_JSON)
+  if (!existsSync(file)) return null
+  try {
+    const snap = JSON.parse(readFileSync(file, 'utf8')) as RemoteSnapshot
+    return snap && snap.version === 1 && snap.items && typeof snap.items === 'object' ? snap : null
+  } catch {
+    return null
+  }
+}
+
+function underDir(root: string, dir: string, rel: string): string {
+  // `safePath` refuses a path that leaves the project; the same rule inside the snapshot folder.
+  safePath(root, rel)
+  return safePath(join(root, dir), rel)
+}
+
+function readUnder(root: string, dir: string, rel: string): string | null {
+  const full = underDir(root, dir, rel)
+  try {
+    return existsSync(full) ? readFileSync(full, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+/** The snapshot's items as the plan reads them; an item whose files went missing is left out. */
+export function snapshotItems(root: string, snap: RemoteSnapshot): RemoteItem[] {
+  return Object.entries(snap.items).flatMap(([ref, s]) => {
+    const files: Record<string, string> = {}
+    for (const path of s.files) {
+      const content = readUnder(root, REMOTE_DIR, path)
+      if (content === null) return []
+      files[path] = content
+    }
+    const assets = (s.assets ?? []).map((path) => ({ path, from: underDir(root, ASSETS_DIR, path) }))
+    return [{ ref, kind: s.kind, name: s.name, title: s.title, files, version: s.version, id: s.id, revision: s.revision, unresolved: s.unresolved, notes: s.notes, requires: s.requires, ...(s.portability ? { portability: s.portability } : {}), ...(s.state ? { state: s.state } : {}), ...(assets.length ? { assets } : {}) }]
+  })
+}
+
+/**
+ * Whether the fetched workspace runs governed Actions: an item needs one by
+ * name or by the platform's id, or names one the read could not. With a
+ * workspace key alone the Actions cannot be read (§15.1), so Forge asks for
+ * an organization key when this is true.
+ */
+export function usesGovernedActions(snap: RemoteSnapshot | null): boolean {
+  if (!snap) return false
+  return Object.values(snap.items).some(
+    (it) => it.portability?.needs.some((n) => n.kind === 'action' || n.kind === 'action-unnamed') || it.unresolved.some((u) => u.kind === 'action'),
+  )
+}
+
+/** Whether a ref's absence from the snapshot means the workspace deleted it. */
+export function knownGone(snap: RemoteSnapshot | null): (ref: string) => boolean {
+  if (!snap || snap.full || !snap.fullIndexAt) return () => false
+  const kinds = new Set(snap.kinds)
+  return (ref) => kinds.has(ref.split('/')[0] as SyncKind) && !(ref in snap.items)
+}
+
+/** `.frontera/` keeps the runtime's state out of git; the snapshot and the base stay out too. */
+function ignoreSyncDir(root: string): void {
+  const ignore = join(root, '.frontera', '.gitignore')
+  mkdirSync(dirname(ignore), { recursive: true })
+  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : ''
+  if (text.split(/\r?\n/).some((l) => l.trim() === 'sync/' || l.trim() === 'sync')) return
+  if (text) appendFileSync(ignore, `${text.endsWith('\n') ? '' : '\n'}sync/\n`)
+  else writeFileSync(ignore, 'local/\nsync/\n')
+}
+
+function toSnapshotItem(item: RemoteItem, revision?: string): SnapshotItem {
+  return {
+    kind: item.kind,
+    name: item.name,
+    title: item.title,
+    ...(item.id ? { id: item.id } : {}),
+    ...(revision ?? item.revision ? { revision: revision ?? item.revision } : {}),
+    hash: itemHash(item.files),
+    files: Object.keys(item.files).sort(),
+    ...(item.version ? { version: item.version } : {}),
+    unresolved: item.unresolved,
+    notes: item.notes,
+    requires: item.requires ?? [],
+    ...(item.portability ? { portability: item.portability } : {}),
+    ...(item.state ? { state: item.state } : {}),
+    ...(item.assets?.length ? { assets: item.assets.map((a) => a.path).sort() } : {}),
+  }
+}
+
+/**
+ * Write the snapshot: the changed items' files, the removed items' files
+ * gone (unless another item holds the path), then `remote.json` last and
+ * atomically, so a reader sees the old snapshot or the new one.
+ */
+function writeSnapshot(root: string, previous: RemoteSnapshot | null, next: RemoteSnapshot, changed: RemoteItem[]): void {
+  ignoreSyncDir(root)
+  const held = new Set(Object.values(next.items).flatMap((i) => i.files))
+  const heldAssets = new Set(Object.values(next.items).flatMap((i) => i.assets ?? []))
+  for (const item of changed) {
+    for (const [path, content] of Object.entries(item.files)) {
+      const full = underDir(root, REMOTE_DIR, path)
+      mkdirSync(dirname(full), { recursive: true })
+      writeFileSync(full, content)
+    }
+    for (const asset of item.assets ?? []) {
+      if (!asset.bytes) continue
+      const full = underDir(root, ASSETS_DIR, asset.path)
+      mkdirSync(dirname(full), { recursive: true })
+      writeFileSync(full, asset.bytes)
+    }
+  }
+  for (const old of Object.values(previous?.items ?? {})) {
+    for (const path of old.files) if (!held.has(path)) rmSync(underDir(root, REMOTE_DIR, path), { force: true })
+    for (const path of old.assets ?? []) if (!heldAssets.has(path)) rmSync(underDir(root, ASSETS_DIR, path), { force: true })
+  }
+  writeFileAtomic(join(root, REMOTE_JSON), `${JSON.stringify(next, null, 2)}\n`, 0o644)
+}
+
+/** Keep what a pull wrote as the base the next merge starts from; a path the item no longer has leaves the base. */
+export function writeBase(root: string, items: RemoteItem[], previous: SyncLock | null): void {
+  ignoreSyncDir(root)
+  for (const item of items) {
+    for (const path of Object.keys(previous?.items[item.ref]?.files ?? {})) {
+      if (!(path in item.files)) rmSync(underDir(root, BASE_DIR, path), { force: true })
+    }
+    for (const [path, content] of Object.entries(item.files)) {
+      const full = underDir(root, BASE_DIR, path)
+      mkdirSync(dirname(full), { recursive: true })
+      writeFileSync(full, content)
+    }
+  }
+}
+
+/** A base file as last pulled, or null. */
+export function readBase(root: string, path: string): string | null {
+  return readUnder(root, BASE_DIR, path)
+}
+
+const CLEARED_JSON = join(SYNC_DIR, 'cleared.json')
+
+/**
+ * Conflicts a later workspace change cleared (the newer version merged
+ * cleanly with the files here, and the merge was written), by ref, with the
+ * base they left: the plan says so while the item's base is still that one.
+ */
+export type ClearedConflicts = Record<string, { at: string; base: string }>
+
+export function readCleared(root: string): ClearedConflicts {
+  const file = join(root, CLEARED_JSON)
+  try {
+    const parsed = existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as ClearedConflicts) : {}
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+export function markCleared(root: string, cleared: ClearedConflicts): void {
+  if (!Object.keys(cleared).length) return
+  ignoreSyncDir(root)
+  writeFileAtomic(join(root, CLEARED_JSON), `${JSON.stringify({ ...readCleared(root), ...cleared }, null, 2)}\n`, 0o644)
+}
+
+/** Forget base files: an item no longer tracked has no base. */
+export function dropBase(root: string, paths: string[]): void {
+  for (const path of paths) rmSync(underDir(root, BASE_DIR, path), { force: true })
+}
+
+// ── Fetch ────────────────────────────────────────────────────────────────────
+
+interface Capabilities { version?: number; platformVersion?: string; features?: string[] }
+interface IndexItem { ref: string; id: string; kind: string; revision: string; group?: boolean; deleted?: boolean }
+interface IndexAnswer { cursor: string; full: boolean; kinds: string[]; items: IndexItem[] }
+
+export interface FetchResult {
+  snapshot: RemoteSnapshot
+  /** Refs whose content was read this time. */
+  changed: string[]
+  /** Refs that left the snapshot. */
+  removed: string[]
+  /** The index was read whole (or the platform has none and everything was read). */
+  fullIndex: boolean
+}
+
+export interface FetchOptions {
+  blueprint?: 'workspace' | 'organization'
+  /** Read the whole index, and with it every deletion, even when the cursor is recent. */
+  full?: boolean
+  now?: Date
+}
+
+const isKind = (k: string): k is SyncKind => (SYNC_KINDS as readonly string[]).includes(k)
+
+const WARNING_LABEL: Partial<Record<SyncKind, [string, string]>> = {
+  agent: ['Agent', 'Agents'],
+  workflow: ['Workflow', 'Workflows'],
+  function: ['Function', 'Functions'],
+  skill: ['Skill', 'Skills'],
+  knowledge: ['Knowledge', 'Knowledge'],
+  plugin: ['Plugin', 'Plugins'],
+}
+
+/** Whether the read warned about this ref, or about its whole kind's list. */
+export function readFailed(warnings: string[], ref: string): boolean {
+  const [kind, ...rest] = ref.split('/')
+  const label = WARNING_LABEL[kind as SyncKind]
+  if (!label) return false
+  const name = rest.join('/')
+  return warnings.some((w) => w.startsWith(`${label[0]} ${name}:`) || w.startsWith(`${label[1]}:`))
+}
+
+/** A read that warned because the platform stopped answering (no answer, or a gateway's 502, 503 or 504) is not a partial view: it is a failed fetch. One item that fails (a 500) is retried on its own next time. */
+function unanswered(warnings: string[]): string | null {
+  return warnings.find((w) => / did not answer: | answered 50[234]: /.test(w)) ?? null
+}
+
+/**
+ * The read, unless the platform stopped answering while it ran: then the
+ * fetch fails, and the snapshot stays as the last good fetch left it, instead
+ * of being written with what happened to come back (which reads as "deleted"
+ * or "up to date").
+ */
+function stopIfUnanswered<T extends { warnings: string[] }>(read: T): T {
+  const why = unanswered(read.warnings)
+  if (why) throw new CliError(`the workspace could not be read: ${why}`, { code: 'UNAVAILABLE', hint: 'the last fetch is kept; check the platform is running and reachable, then fetch again' })
+  return read
+}
+
+/**
+ * Bring the snapshot up to date. On a platform with the sync index: read the
+ * capabilities, the index (from the saved cursor, or whole when there is
+ * none, when `full`, or once an hour), then only the changed items' content.
+ * On an older platform: read the whole workspace, and say so (`full: true`).
+ */
+export async function fetchWorkspace(root: string, source: SyncSource, opts: FetchOptions = {}): Promise<FetchResult> {
+  const now = opts.now ?? new Date()
+  const stored = readSnapshot(root)
+  const previous = stored?.workspace === source.workspaceId ? stored : null
+  // Keys that read more (or less) than the snapshot's did, or a CLI that reads more of an
+  // item than the one that took it: everything is read again.
+  const keysChanged = !!previous && (!!previous.organizationKey !== !!source.organization || (previous.reader ?? 1) < SNAPSHOT_READER)
+  // A platform without the route answers 404 (`find` gives null) and is read the older way. One that does
+  // not answer, or fails (5xx), is not an older platform: the fetch stops and the last snapshot stays.
+  const caps = await source.workspace.find<Capabilities>('/v1/sync/capabilities').catch((err: Error) => {
+    const code = (err as { code?: string }).code
+    if (code === 'UNAUTHORIZED' || code === 'UNAVAILABLE') throw err
+    return null
+  })
+  const capabilities = caps?.features ?? []
+  const platformVersion = caps?.platformVersion ?? null
+
+  // Read on every fetch: small, and it has no revision of its own.
+  const settings = capabilities.includes('settings') ? await readOrgSettings(source.workspace) : null
+  if (!capabilities.includes('index')) {
+    const read = stopIfUnanswered(await readWorkspace(source, { blueprint: opts.blueprint }))
+    const items = Object.fromEntries(read.items.map((i) => [i.ref, toSnapshotItem(i)]))
+    const next: RemoteSnapshot = {
+      version: 1,
+      workspace: source.workspaceId,
+      cursor: null,
+      fetchedAt: now.toISOString(),
+      fullIndexAt: null,
+      full: true,
+      platformVersion,
+      capabilities,
+      kinds: [],
+      groups: {},
+      skipped: {},
+      items,
+      warnings: read.warnings,
+      notes: read.notes,
+      names: namesOf(read.directory),
+      organizationKey: !!source.organization,
+      reader: SNAPSHOT_READER,
+      ...(settings ? { settings } : {}),
+    }
+    const changed = read.items.filter((i) => previous?.items[i.ref]?.hash !== itemHash(i.files))
+    writeSnapshot(root, previous, next, read.items)
+    return { snapshot: next, changed: changed.map((i) => i.ref), removed: Object.keys(previous?.items ?? {}).filter((r) => !(r in items)), fullIndex: true }
+  }
+
+  const recentFull = previous?.fullIndexAt && now.getTime() - Date.parse(previous.fullIndexAt) < FULL_INDEX_EVERY_MS
+  const since = !opts.full && !keysChanged && previous && !previous.full && previous.cursor && recentFull ? previous.cursor : null
+  const index = await source.workspace.get<IndexAnswer>(`/v1/sync/index${since ? `?since=${encodeURIComponent(since)}` : ''}`)
+  const kinds = index.kinds.filter(isKind)
+  const items: Record<string, SnapshotItem> = previous && !previous.full && !keysChanged ? { ...previous.items } : {}
+  const groups: Partial<Record<SyncKind, string>> = previous && !previous.full && !keysChanged ? { ...previous.groups } : {}
+  const skipped: Record<string, string> = previous && !previous.full && !keysChanged ? { ...previous.skipped } : {}
+  const removed = new Set<string>()
+  const drop = (ref: string) => {
+    if (ref in items) removed.add(ref)
+    delete items[ref]
+  }
+
+  // What to read: items whose revision moved (or that the snapshot lacks), and kinds read whole whose revision moved.
+  const only = new Set<string>()
+  const readKinds = new Set<SyncKind>()
+  const regroup = new Set<SyncKind>()
+  const listed = new Set<string>()
+  for (const entry of index.items) {
+    if (!isKind(entry.kind)) continue
+    if (entry.group || GROUP_KINDS.includes(entry.kind)) {
+      if (groups[entry.kind] !== entry.revision) {
+        readKinds.add(entry.kind)
+        regroup.add(entry.kind)
+      }
+      continue
+    }
+    listed.add(entry.ref)
+    // A rename: the same platform id under another name leaves its old name.
+    for (const [ref, it] of Object.entries(items)) if (it.id === entry.id && ref !== entry.ref && it.kind === entry.kind) drop(ref)
+    const have = items[entry.ref]?.revision ?? skipped[entry.ref]
+    if (have === entry.revision) continue
+    only.add(entry.ref)
+    readKinds.add(entry.kind)
+  }
+  // A whole index lists everything there is: what it does not list, of a kind it covers, is gone.
+  if (index.full) {
+    const groupsListed = new Set(index.items.filter((e) => e.group || GROUP_KINDS.includes(e.kind as SyncKind)).map((e) => e.kind))
+    for (const [ref, it] of Object.entries(items)) {
+      if (!kinds.includes(it.kind)) continue
+      if (GROUP_KINDS.includes(it.kind) ? !groupsListed.has(it.kind) : !listed.has(ref)) drop(ref)
+    }
+    for (const kind of GROUP_KINDS) if (kinds.includes(kind) && !groupsListed.has(kind)) delete groups[kind]
+    for (const ref of Object.keys(skipped)) if (!listed.has(ref)) delete skipped[ref]
+  }
+
+  let read: Awaited<ReturnType<typeof readWorkspace>> | null = null
+  if (readKinds.size) {
+    // The Blueprint and evaluations are read whole whatever `only` says.
+    read = stopIfUnanswered(await readWorkspace(source, { kinds: readKinds, only, blueprint: opts.blueprint }))
+  }
+  const revisionOf = new Map(index.items.map((e) => [e.ref, e.revision]))
+  const got = read?.items ?? []
+  // A kind read whole replaces every item of that kind.
+  for (const kind of regroup) {
+    for (const [ref, it] of Object.entries(items)) if (it.kind === kind && !got.some((g) => g.ref === ref)) drop(ref)
+    const entry = index.items.find((e) => e.kind === kind)
+    if (entry) groups[kind] = entry.revision
+  }
+  for (const it of got) {
+    if (!regroup.has(it.kind) && !only.has(it.ref)) continue
+    // A kind read whole carries its group's revision (the Blueprint's release), so a pull records it
+    // in the lock and a lost base can be read again at it.
+    items[it.ref] = toSnapshotItem(it, regroup.has(it.kind) ? groups[it.kind] : revisionOf.get(it.ref))
+    removed.delete(it.ref)
+    delete skipped[it.ref]
+  }
+  // Listed but nothing came back and nothing failed: a thing with no files (a workflow without a
+  // definition). Remembered by revision so it is not read again until it changes; a failed read is retried.
+  for (const ref of only) {
+    if (got.some((g) => g.ref === ref) || readFailed(read?.warnings ?? [], ref)) continue
+    skipped[ref] = revisionOf.get(ref)!
+  }
+
+  const next: RemoteSnapshot = {
+    version: 1,
+    workspace: source.workspaceId,
+    cursor: index.cursor,
+    fetchedAt: now.toISOString(),
+    fullIndexAt: index.full ? now.toISOString() : previous?.fullIndexAt ?? null,
+    full: false,
+    platformVersion,
+    capabilities,
+    kinds,
+    groups,
+    skipped,
+    items,
+    warnings: read?.warnings ?? [],
+    notes: read ? read.notes : previous?.notes ?? [],
+    ...(read ? { names: namesOf(read.directory) } : previous?.names ? { names: previous.names } : {}),
+    organizationKey: !!source.organization,
+    reader: SNAPSHOT_READER,
+    ...(settings ? { settings } : previous?.settings ? { settings: previous.settings } : {}),
+  }
+  writeSnapshot(root, previous, next, got.filter((g) => g.ref in items))
+  return { snapshot: next, changed: got.filter((g) => g.ref in items).map((g) => g.ref), removed: [...removed], fullIndex: index.full }
+}