@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/commands/local/sync-request.ts

@@ -0,0 +1,750 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { CliError, UsageError } from '../../errors'
+import { documentPath, readFolders, readPulledDocuments, recordPulledDocuments, sha256Of, type PulledDocument } from '../../local/local-knowledge-documents'
+import { assetFilename } from '../skill/bundle-commands'
+import { packDirectory } from '../../pack'
+import { createTarGz } from '../../tar'
+import { functionEntry } from '../../local/local-dev-sync'
+import { adoptProposedLessons } from '../../local/local-lessons'
+import { localProject, type LocalProject } from '../../local/local-project'
+import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
+import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
+import { getSyncKey, readLink, type SyncLink } from '../../local/local-sync-link'
+import { itemTitle } from '../../local/local-sync-names'
+import { readLock, type SyncKind } from '../../local/local-sync-plan'
+import {
+  adoptApplied,
+  checksOf,
+  currentRequest,
+  describeOutcome,
+  functionEntryOf,
+  isOpen,
+  itemLine,
+  KIND_WORD,
+  needsOrganizationKey,
+  parseOutcome,
+  projectRefs,
+  pushBody,
+  pushCandidates,
+  pushItemLine,
+  readRequestBase,
+  readRequests,
+  recordRequest,
+  writeRequestBase,
+  type ApplyOutcome,
+  type Check,
+  type FunctionBuild,
+  type PushAsset,
+  type PushItem,
+} from '../../local/local-sync-push'
+import { directoryOf, readSnapshot, snapshotItems } from '../../local/local-sync-snapshot'
+import { buildAndExtract } from '../automation/build-entry'
+import { findAutomationProjectRoot } from '../automation/project-root'
+import { flagBool, flagString, type CommandContext } from '../types'
+import { fetchFor, planFor, sourceFor } from './sync'
+
+/**
+ * `frontera local sync push` and `frontera local sync request`: change
+ * requests v1 from the project (design 2026-10-17 §4, §7, §11).
+ *
+ *   push [ref…] -t <title>   fetch, then propose what changed here as one change request
+ *                            (the current one is updated, and then holds what this push sent:
+ *                            name items to propose only those); `--preview` lists it in words
+ *   request [show]           the current request: its items, each against its base, and what happened
+ *   request apply            apply it: each step moves a live version, and a failure puts every earlier one back;
+ *                            then fetch, so the applied items read as up to date
+ *   request close            close it without applying
+ *
+ * The request's id is kept in `.frontera/sync/requests.json` (not
+ * committed). Keys come from the keychain, as for `sync fetch`; the
+ * organization key goes beside the workspace key only when Apply has
+ * Blueprint items.
+ */
+
+const ORGANIZATION_KEY_HEADER = 'x-frontera-organization-key'
+
+function needLink(project: LocalProject): SyncLink {
+  const link = readLink(project.root)
+  if (!link) throw new CliError('this project is not linked to a workspace', { code: 'SYNC_NOT_LINKED', hint: 'run `frontera local sync connect --platform <url>` with a workspace key' })
+  return link
+}
+
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+
+// ── The platform ────────────────────────────────────────────────────────────
+
+type RequestBody = NonNullable<RequestInit['body']>
+
+interface Platform {
+  call<T>(method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown, opts?: { organizationKey?: string | null; timeoutMs?: number }): Promise<T>
+  /** A body sent as it is (a document's bytes, a multipart upload), not as JSON. */
+  send<T>(method: 'POST' | 'PUT', path: string, body: RequestBody, contentType: string | null, opts?: { timeoutMs?: number }): Promise<T>
+}
+
+/**
+ * The change-request routes with the project's workspace key. A refusal by
+ * the blocking checks keeps them (`details.checks`), so the caller can say
+ * which item each names; Apply may take minutes, so it waits longer than a
+ * read.
+ */
+function platform(link: SyncLink, key: string): Platform {
+  const origin = normalizeOrigin(link.platform)
+  const request = async (method: string, path: string, headers: Record<string, string>, body: RequestBody | undefined, timeoutMs: number): Promise<Response> => {
+    try {
+      return await fetch(new URL(path, origin), { method, headers: { authorization: `Bearer ${key}`, accept: 'application/json', ...headers }, body, signal: AbortSignal.timeout(timeoutMs) })
+    } catch (err) {
+      throw new CliError(`${origin} did not answer: ${(err as Error).message}`, { code: 'UNAVAILABLE', hint: 'check the address and your network, then run the command again' })
+    }
+  }
+  return {
+    async call<T>(method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown, opts: { organizationKey?: string | null; timeoutMs?: number } = {}): Promise<T> {
+      const res = await request(method, path, {
+        ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        ...(opts.organizationKey ? { [ORGANIZATION_KEY_HEADER]: opts.organizationKey } : {}),
+      }, body === undefined ? undefined : JSON.stringify(body), opts.timeoutMs ?? 60_000)
+      return answer<T>(res)
+    },
+    async send<T>(method: 'POST' | 'PUT', path: string, body: RequestBody, contentType: string | null, opts: { timeoutMs?: number } = {}): Promise<T> {
+      return answer<T>(await request(method, path, contentType ? { 'content-type': contentType } : {}, body, opts.timeoutMs ?? 300_000))
+    },
+  }
+}
+
+/** A platform answer: its data, or a refusal in words (the checks it names kept in `details`). */
+async function answer<T>(res: Response): Promise<T> {
+  const text = await res.text().catch(() => '')
+  let parsed: Record<string, unknown> | null = null
+  try {
+    parsed = text ? (JSON.parse(text) as Record<string, unknown>) : null
+  } catch {
+    parsed = null
+  }
+  if (res.ok) return unwrap<T>(parsed)
+  const message = String(parsed?.message ?? (typeof parsed?.error === 'string' ? parsed.error : '') ?? '').trim() || text.slice(0, 300) || `the platform answered ${res.status}`
+  const checks = checksOf(parsed?.details)
+  if (checks.length) throw new CliError(message, { code: 'SYNC_CHECKS', hint: 'fix the items the checks name, then push again', details: { checks } })
+  if (res.status === 401) throw new CliError('the platform refused the key', { code: 'UNAUTHORIZED', hint: 'check it is a current workspace key (sk-ws-…) for this platform; `frontera local sync connect` stores a new one' })
+  if (res.status === 403) throw new CliError(message, { code: 'FORBIDDEN', hint: 'the key’s role decides what it may propose and apply; ask a workspace admin' })
+  if (res.status === 404) throw new CliError(message, { code: 'NOT_FOUND', hint: 'the change request is gone from the workspace; propose again with `frontera local sync push`' })
+  if (res.status === 409) throw new CliError(message, { code: 'CONFLICT', hint: 'see where it stands with `frontera local sync request`' })
+  if (res.status === 400 || res.status === 422) throw new CliError(message, { code: 'VALIDATION_ERROR', hint: 'see where it stands with `frontera local sync request`' })
+  throw new CliError(`the platform answered ${res.status}: ${message}`, { code: 'UNAVAILABLE', hint: 'check the platform is reachable, then run the command again' })
+}
+
+function platformFor(project: LocalProject, link: SyncLink): Platform {
+  const key = getSyncKey(project, 'workspace')
+  if (!key) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (keys are per machine)' })
+  return platform(link, key)
+}
+
+// ── The platform's view of a request ────────────────────────────────────────
+
+interface ViewItem {
+  id: string
+  ref: string
+  kind: SyncKind
+  name: string
+  baseRevision: string | null
+  state: string
+  error: string | null
+  mergedRevision: string | null
+  files: Record<string, string>
+  build?: { bundleBytes: number; hasSource: boolean } | null
+  reviews?: Array<{ verdict: string; current: boolean; reviewerId: string }>
+  deleted?: boolean
+  assets?: Array<{ path: string; bytes: number; sha256: string }>
+  documents?: { upload: Array<{ fileName: string; folder?: string | null; sha256: string; bytes: number; replaces?: string | null; staged?: boolean }>; remove: Array<{ fileName: string; sourceId: string }> }
+}
+
+interface View {
+  request: { id: string; title: string; description: string | null; state: string; authorId: string; createdAt: string; updatedAt: string; mergedAt: string | null; closedAt?: string | null }
+  items: ViewItem[]
+  events: Array<{ id: string; kind: string; actorId: string; detail: Record<string, unknown> | null; createdAt: string }>
+  outcome?: unknown
+}
+
+const STATE_WORD: Record<string, string> = {
+  draft: 'Draft',
+  open: 'Proposed',
+  approved: 'Approved',
+  merging: 'Applying',
+  merged: 'Applied',
+  closed: 'Closed',
+}
+
+const ITEM_STATE_WORD: Record<string, string> = {
+  open: 'In review',
+  approved: 'Approved',
+  changes_requested: 'Changes requested',
+  merged: 'Applied',
+}
+
+function checkLines(checks: Check[], titles: Record<string, string>): string[] {
+  return checks.map((c) => `  ${titles[c.ref] ?? c.ref}: ${c.message}`)
+}
+
+// ── push ────────────────────────────────────────────────────────────────────
+
+/** Each Function built as `function deploy` builds it, base64, with its project's source. */
+export function functionBuilder(project: Pick<LocalProject, 'root'>, ctx: Pick<CommandContext, 'output'>) {
+  return async (item: PushItem): Promise<FunctionBuild> => {
+    const entry = functionEntryOf(project.root, item.name, functionEntry)
+    const { manifest, code } = await buildAndExtract(join(project.root, entry))
+    // Its project's source, as `function deploy` keeps it, so a pull can bring it back; never a folder above this
+    // project. A project without its own package.json keeps the Function's files instead, at their project paths.
+    const root = resolve(project.root)
+    const at = findAutomationProjectRoot(resolve(root, entry))
+    const inside = at !== null && (at === root || at.startsWith(`${root}/`))
+    const tgz = inside
+      ? packDirectory(at!, ctx.output, `source of ${item.name}`).tgz
+      : createTarGz(Object.entries(item.files).map(([rel, text]) => ({ rel, bytes: new TextEncoder().encode(text) })))
+    const source = Buffer.from(tgz).toString('base64')
+    return { manifest, bundle: Buffer.from(code, 'utf8').toString('base64'), source }
+  }
+}
+
+function itemJson(item: PushItem) {
+  return {
+    ref: item.ref,
+    kind: item.kind,
+    name: item.name,
+    title: item.title,
+    change: item.change,
+    line: pushItemLine(item),
+    proposable: item.proposable,
+    blocked: item.blocked,
+    reason: item.reason,
+    files: item.diff,
+    notes: item.notes,
+    ...(item.assets ? { assets: item.assets.map((a) => ({ path: a.path, bytes: a.bytes, change: a.change })) } : {}),
+    ...(item.documents ? { documents: item.documents } : {}),
+  }
+}
+
+/** Each asset a skill item sends, uploaded as `frontera skill push` uploads them (content-addressed); the storage key back. */
+function assetUploader(project: Pick<LocalProject, 'root'>, api: Platform) {
+  return async (_item: PushItem, asset: PushAsset): Promise<string> => {
+    const bytes = new Uint8Array(readFileSync(join(project.root, asset.file)))
+    const form = new FormData()
+    form.set('file', new File([bytes], asset.path.split('/').pop()!, { type: asset.mime }))
+    form.set('purpose', 'skill-asset')
+    const uploaded = await api.send<{ storagePath?: string; data?: { storagePath?: string } }>('POST', '/v1/upload', form, null, { timeoutMs: 120_000 })
+    const storagePath = uploaded?.storagePath ?? uploaded?.data?.storagePath
+    if (typeof storagePath !== 'string' || !assetFilename(storagePath)?.startsWith(asset.sha256.slice(0, 16))) {
+      throw new CliError(`skills: ${asset.file} was not stored as the platform keeps skill assets`, { code: 'UNAVAILABLE', hint: 'check the file is an image, font or template the platform takes, then push again' })
+    }
+    return storagePath
+  }
+}
+
+/** The documents each knowledge base item lists that the request does not hold yet, sent one at a time. */
+async function stageDocuments(project: Pick<LocalProject, 'root'>, api: Platform, view: View): Promise<number> {
+  let sent = 0
+  for (const item of view.items) {
+    if (item.kind !== 'knowledge' || !item.documents) continue
+    for (const doc of item.documents.upload) {
+      if (doc.staged) continue
+      const path = documentPath(doc.folder, doc.fileName)
+      const bytes = new Uint8Array(readFileSync(join(project.root, 'knowledge', item.name, path)))
+      if (sha256Of(bytes) !== doc.sha256) throw new CliError(`knowledge/${item.name}/${path} changed while it was proposed`, { code: 'CONFLICT', hint: 'push again' })
+      await api.send('PUT', `/v1/change-requests/${view.request.id}/documents/${doc.sha256}`, bytes, 'application/octet-stream', { timeoutMs: 300_000 })
+      sent++
+    }
+  }
+  return sent
+}
+
+/** What the workspace holds of each knowledge base whose documents are brought: its documents by name. */
+async function platformDocuments(api: Platform, names: string[], remote: Array<{ ref: string; id?: string }>): Promise<Map<string, Array<{ id: string; fileName: string }>>> {
+  const out = new Map<string, Array<{ id: string; fileName: string }>>()
+  for (const name of names) {
+    const id = remote.find((r) => r.ref === `knowledge/${name}`)?.id
+    if (!id) {
+      out.set(name, [])
+      continue
+    }
+    const listed = await api.call<unknown>('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
+    const rows = (Array.isArray(listed) ? listed : ((listed as { sources?: unknown[]; data?: unknown[] })?.sources ?? (listed as { data?: unknown[] })?.data ?? [])) as Array<{ id?: string; fileName?: string | null; folderId?: string | null }>
+    // By path under the knowledge base's folder, as the project files them.
+    const folders = rows.some((r) => r.folderId) ? await readFolders({ get: (path) => api.call<unknown>('GET', path) }, id) : new Map<string, string>()
+    out.set(name, rows.flatMap((r) => (r.id && r.fileName ? [{ id: r.id, fileName: documentPath(r.folderId ? folders.get(r.folderId) : null, r.fileName) }] : [])))
+  }
+  return out
+}
+
+/**
+ * What still uses each item this push would delete, read with the platform's
+ * own in-use check before anything is proposed, so a deletion names its
+ * dependents first. An older platform without the read says nothing.
+ */
+async function deletionUsers(project: LocalProject, link: SyncLink, items: PushItem[]): Promise<Map<string, string[]>> {
+  const refs = items.filter((i) => i.change === 'deleted' && i.proposable && i.kind !== 'blueprint').map((i) => i.ref)
+  if (!refs.length) return new Map()
+  try {
+    const answer = await platformFor(project, link).call<{ items: Array<{ ref: string; usedBy: string[] }> }>('POST', '/v1/change-requests/usage', { refs })
+    return new Map((answer.items ?? []).filter((u) => u.usedBy.length).map((u) => [u.ref, u.usedBy]))
+  } catch {
+    return new Map()
+  }
+}
+
+function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map()): string {
+  const ok = items.filter((i) => i.proposable)
+  const not = items.filter((i) => !i.proposable)
+  const name = link.workspaceName ?? link.workspace
+  const lines = [
+    ok.length ? `Would propose ${plural(ok.length, 'item')} to ${name}${kept ? `, updating “${kept.title}”` : ''}:` : `Nothing to propose to ${name}.`,
+    // Each item's notes under it.
+    ...ok.flatMap((i) => [`  [x] ${pushItemLine(i)}`, ...(usedBy.has(i.ref) ? [`      ! Still used by ${usedBy.get(i.ref)!.join(', ')}: applying would be refused`] : []), ...i.notes.map((n) => `      · ${n}`)]),
+  ]
+  if (not.length) lines.push('', 'Not proposed:', ...not.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`))
+  if (orgNote) lines.push('', orgNote)
+  if (!available) lines.push('', 'This platform does not take change requests yet.')
+  if (ok.length && available) lines.push('', 'Propose with `frontera local sync push -t "<title>"`, or name items to propose only those.')
+  return lines.join('\n')
+}
+
+export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const named = ctx.positional.slice(1)
+  const preview = flagBool(ctx, 'preview')
+  // Fetch first, as git does before a push: an item the workspace moved past is pulled and merged first.
+  const { plan, lock, snapshot, remote } = await planFor(project, link, { fetch: 'always', repair: 'online' })
+  if (!plan || !snapshot) throw new CliError('could not fetch the workspace', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch` and look at what it says' })
+  const available = snapshot.capabilities.includes('change-requests')
+  // Knowledge bases whose documents come too: opt-in, as for a pull (`*` for every one the project has).
+  const asked = (flagString(ctx, 'documents') ?? '').split(',').map((s) => s.trim().replace(/^knowledge\//, '')).filter(Boolean)
+  const knowledgeHere = [...projectRefs(project.root).values()].filter((r) => r.kind === 'knowledge').map((r) => r.name)
+  const documentNames = asked.includes('*') ? knowledgeHere : asked
+  const notHere = documentNames.filter((n) => !knowledgeHere.includes(n))
+  if (notHere.length) throw new UsageError(`no knowledge base ${notHere.join(', ')} in this project`, '--documents takes knowledge base names (knowledge/<name>), or * for every one')
+  const documents = documentNames.length
+    ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(platformFor(project, link), documentNames, remote.items) }
+    : undefined
+  const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, ...(documents ? { documents } : {}) })
+  const kept = currentRequest(readRequests(project.root, link.workspace))
+  const updating = kept && isOpen(kept.state) ? kept : null
+  const orgStored = !!getSyncKey(project, 'organization')
+  const titles = Object.fromEntries(all.map((i) => [i.ref, i.title]))
+
+  let chosen: PushItem[]
+  if (named.length) {
+    const byRef = new Map(all.map((i) => [i.ref, i]))
+    const unknown = named.filter((r) => !byRef.has(r))
+    if (unknown.length) throw new UsageError(`nothing to propose in ${unknown.join(', ')}: ${unknown.length === 1 ? 'it matches' : 'they match'} the workspace, or the project has no such item`, 'list what can be proposed with `frontera local sync push --preview`')
+    chosen = named.map((r) => byRef.get(r)!)
+  } else chosen = all
+  const orgNote = needsOrganizationKey(chosen) ? (orgStored ? 'Blueprint changes are applied with the organization key stored for this project.' : 'Blueprint changes need the organization key to apply: connect again with `--org-key -` before applying.') : null
+
+  if (preview) {
+    const usedBy = available ? await deletionUsers(project, link, chosen) : new Map<string, string[]>()
+    return {
+      data: {
+        link,
+        available,
+        request: updating ? { id: updating.id, title: updating.title, state: updating.state, items: updating.refs.length, refs: updating.refs } : null,
+        items: chosen.map((i) => ({ ...itemJson(i), ...(usedBy.has(i.ref) ? { usedBy: usedBy.get(i.ref) } : {}) })),
+        counts: { proposable: chosen.filter((i) => i.proposable).length, blocked: chosen.filter((i) => !i.proposable).length },
+        organizationKey: { needed: needsOrganizationKey(chosen), stored: orgStored },
+        fetchedAt: snapshot.fetchedAt,
+      },
+      text: previewText(link, chosen, updating, orgNote, available, usedBy),
+    }
+  }
+
+  if (!available) throw new CliError(`${link.workspaceName ?? 'this workspace'}’s platform does not take change requests yet`, { code: 'SYNC_NO_CHANGE_REQUESTS', hint: 'make the change on the platform, or ask your administrator to update it' })
+  // Named items must each be proposable; with none named, an item the workspace moved past stops the push.
+  const stopping = chosen.filter((i) => !i.proposable && (named.length > 0 || i.blocked === 'moved' || i.blocked === 'conflicts'))
+  if (stopping.length) {
+    const lines = stopping.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)
+    throw new CliError(`not proposed: ${plural(stopping.length, 'item')} cannot go yet\n${lines.join('\n')}`, {
+      code: 'SYNC_PUSH_BLOCKED',
+      hint: stopping.some((i) => i.blocked === 'moved' || i.blocked === 'conflicts') ? 'pull and merge them first (`frontera local sync pull <ref>`), or name the items to propose' : 'name only items that can be proposed; `--preview` lists them',
+      details: { blocked: stopping.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })) },
+    })
+  }
+  const going = chosen.filter((i) => i.proposable)
+  if (!going.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
+  const title = flagString(ctx, 'title')?.trim()
+  const description = flagString(ctx, 'description')
+  const api = platformFor(project, link)
+  // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
+  let target = updating
+  if (target) {
+    const live = await api.call<View>('GET', `/v1/change-requests/${target.id}`).catch((err: CliError) => (err.code === 'NOT_FOUND' ? null : Promise.reject(err)))
+    if (!live || !isOpen(live.request.state)) {
+      if (live) recordRequest(project.root, link.workspace, live)
+      target = null
+    }
+  }
+  if (!target && !title) throw new UsageError('give the change request a title', 'frontera local sync push -t "Tighten the refund procedure"')
+
+  const items = await pushBody(going, functionBuilder(project, ctx), assetUploader(project, api))
+  let view: View
+  try {
+    view = target
+      ? await api.call<View>('PUT', `/v1/change-requests/${target.id}`, { ...(title ? { title } : {}), ...(description !== undefined ? { description: description || null } : {}), items, replace: true }, { timeoutMs: 120_000 })
+      : await api.call<View>('POST', '/v1/change-requests', { title, ...(description ? { description } : {}), items }, { timeoutMs: 120_000 })
+  } catch (err) {
+    if (err instanceof CliError && err.code === 'SYNC_CHECKS') {
+      const checks = checksOf(err.details)
+      throw new CliError(`not proposed: the workspace refused ${plural(checks.length, 'check')}\n${checkLines(checks, titles).join('\n')}`, {
+        code: 'SYNC_PUSH_REFUSED',
+        hint: checks.some((c) => c.code === 'stale_base' || c.code === 'exists' || c.code === 'gone') ? 'fetch and pull the items named, merge them, then push again' : 'fix the items named, then push again',
+        details: { checks },
+      })
+    }
+    throw err
+  }
+  // A knowledge base's documents follow the request, one at a time (each up to the platform's limit).
+  const staged = await stageDocuments(project, api, view)
+  if (staged) view = await api.call<View>('GET', `/v1/change-requests/${view.request.id}`)
+  const allTitles = { ...(kept?.titles ?? {}), ...titles }
+  recordRequest(project.root, link.workspace, view, { titles: allTitles, pushed: true })
+  writeRequestBase(project.root, view.request.id, going)
+  const notProposed = chosen.filter((i) => !i.proposable)
+  return {
+    data: {
+      proposed: true,
+      created: !target,
+      request: { id: view.request.id, title: view.request.title, state: view.request.state, items: view.items.length, refs: view.items.map((i) => i.ref) },
+      pushed: going.map((i) => i.ref),
+      notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })),
+      organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+    },
+    text: [
+      `${target ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${link.workspaceName ?? link.workspace}: ${plural(view.items.length, 'item')}.`,
+      ...going.map((i) => `  ${pushItemLine(i)}`),
+      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)] : []),
+      ...(orgNote ? ['', orgNote] : []),
+      '',
+      'Apply it with `frontera local sync request apply`; see it with `frontera local sync request`.',
+    ].join('\n'),
+  }
+}
+
+// ── request ─────────────────────────────────────────────────────────────────
+
+/** The base each item was changed from: the copy kept at push, the fetched snapshot, or the platform at that revision. */
+async function basesFor(project: LocalProject, link: SyncLink, view: View): Promise<Record<string, { files: Record<string, string>; known: boolean }>> {
+  const kept = readRequestBase(project.root, view.request.id)
+  const snapshot = readSnapshot(project.root)
+  const remote = snapshot && snapshot.workspace === link.workspace ? new Map(snapshotItems(project.root, snapshot).map((i) => [i.ref, i])) : new Map()
+  const out: Record<string, { files: Record<string, string>; known: boolean }> = {}
+  for (const item of view.items) {
+    if (!item.baseRevision) {
+      out[item.ref] = { files: {}, known: true }
+      continue
+    }
+    if (kept.known) {
+      const files: Record<string, string> = {}
+      // A deletion sends no files: its base's paths were kept with the copy.
+      for (const path of item.deleted ? kept.paths(item.ref) : Object.keys(item.files)) {
+        const text = kept.read(path)
+        if (text !== null) files[path] = text
+      }
+      out[item.ref] = { files, known: true }
+      continue
+    }
+    const theirs = remote.get(item.ref)
+    const groupRevision = item.kind === 'blueprint' ? snapshot?.groups.blueprint : theirs?.revision
+    if (theirs && groupRevision === item.baseRevision) {
+      out[item.ref] = { files: theirs.files, known: true }
+      continue
+    }
+    out[item.ref] = { files: {}, known: false }
+    // Earlier versions the platform keeps: workflows, Functions and the Blueprint by revision.
+    if (item.kind === 'agent' || !HISTORY_KINDS.includes(item.kind) || !snapshot?.capabilities.includes('item-revision')) continue
+    try {
+      const source = sourceFor(project, link)
+      const asked = item.kind === 'blueprint' ? 'blueprint' : item.ref
+      const answer = await source.workspace.find<{ ref: string; kind: string; revision: string; content: Record<string, unknown> }>(`/v1/sync/item?ref=${encodeURIComponent(asked)}&revision=${encodeURIComponent(item.baseRevision)}`)
+      if (answer) out[item.ref] = { files: await projectAtRevision(source, item.ref, answer, Object.keys(item.files), directoryOf(snapshot)), known: true }
+    } catch {
+      // Shown without its base; the page says so.
+    }
+  }
+  return out
+}
+
+/** The latest refusal by the checks, when nothing happened to the request since. */
+function lastChecks(view: View): Check[] {
+  const events = [...view.events].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+  const last = events.filter((e) => ['created', 'pushed', 'apply_refused', 'apply_started', 'merged', 'apply_failed', 'closed'].includes(e.kind)).pop()
+  return last?.kind === 'apply_refused' ? checksOf(last.detail) : []
+}
+
+/** What happened to the request, one entry per event, in words. */
+function activityOf(view: View, titles: Record<string, string>) {
+  const name = (ref: unknown) => (typeof ref === 'string' ? titles[ref] ?? ref : 'an item')
+  const names = (refs: unknown) => (Array.isArray(refs) ? refs.map(name).join(', ') : '')
+  return [...view.events]
+    .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+    .map((e) => {
+      const d = (e.detail ?? {}) as Record<string, unknown>
+      const by = e.actorId === view.request.authorId ? 'you' : 'teammate'
+      let text: string
+      let outcome: ApplyOutcome | undefined
+      switch (e.kind) {
+        case 'created':
+          text = `Proposed ${plural(Array.isArray(d.refs) ? d.refs.length : 0, 'item')}`
+          break
+        case 'pushed': {
+          const parts = [
+            Array.isArray(d.added) && d.added.length ? `added ${names(d.added)}` : '',
+            Array.isArray(d.changed) && d.changed.length ? `updated ${names(d.changed)}` : '',
+            Array.isArray(d.removed) && d.removed.length ? `took out ${names(d.removed)}` : '',
+          ].filter(Boolean)
+          text = parts.length ? `Pushed: ${parts.join('; ')}` : 'Pushed again; nothing changed'
+          break
+        }
+        case 'approvals_dismissed':
+          text = `The approval on ${name(d.ref)} was dismissed: it changed`
+          break
+        case 'reviewed':
+          text = d.implicit ? 'Approved on Apply' : d.verdict === 'request_changes' ? `Changes requested on ${name(d.ref)}` : `Approved ${name(d.ref)}`
+          break
+        case 'apply_started':
+          text = 'Apply started'
+          break
+        case 'apply_refused':
+          text = `Apply refused: ${plural(checksOf(d).length, 'check')} failed`
+          break
+        case 'apply_failed': {
+          outcome = parseOutcome({ ok: false, steps: d.steps, failure: d.failure, compensation: d.compensation })
+          const failed = outcome.steps.find((s) => s.status === 'failed')
+          text = `Apply failed${failed ? ` at “${failed.label}”` : ''}; ${outcome.compensation.length ? `${plural(outcome.compensation.length, 'change')} put back` : 'nothing had changed'}`
+          break
+        }
+        case 'merged':
+          outcome = parseOutcome({ ok: true, steps: d.steps, compensation: [] })
+          text = `Applied: ${plural(outcome.steps.length, 'step')}`
+          break
+        case 'compensated':
+          text = 'An Apply that stopped part-way was put back'
+          break
+        case 'closed':
+          text = 'Closed'
+          break
+        default:
+          text = e.kind.replace(/_/g, ' ')
+      }
+      return { kind: e.kind, at: e.createdAt, by, text, ...(outcome ? { steps: outcome.steps, compensation: outcome.compensation, failure: outcome.failure ?? null } : {}) }
+    })
+}
+
+async function currentView(project: LocalProject, link: SyncLink): Promise<{ view: View; titles: Record<string, string> } | null> {
+  const kept = currentRequest(readRequests(project.root, link.workspace))
+  if (!kept) return null
+  const view = await platformFor(project, link).call<View>('GET', `/v1/change-requests/${kept.id}`)
+  recordRequest(project.root, link.workspace, view)
+  return { view, titles: kept.titles }
+}
+
+/**
+ * An item of the request by its name today (`local-sync-names.ts`): the
+ * title kept when it was proposed, unless that is only a slug form (a
+ * request proposed before items were named by display name kept "brand"),
+ * then what its proposed files declare. The kept titles are not rewritten.
+ */
+function titleOf(item: ViewItem, titles: Record<string, string>): string {
+  return itemTitle(item.kind, item.name, item.files, titles[item.ref])
+}
+
+async function show(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const current = await currentView(project, link)
+  if (!current) {
+    return { data: { request: null }, text: 'No change request yet. Propose what changed here with `frontera local sync push -t "<title>"`.' }
+  }
+  const { view, titles } = current
+  const bases = await basesFor(project, link, view)
+  const checks = lastChecks(view)
+  const items = view.items.map((item) => {
+    const base = bases[item.ref]!
+    const paths = [...new Set([...Object.keys(base.files), ...Object.keys(item.files)])].sort()
+    const files = paths.map((path) => ({ path, base: base.files[path] ?? null, local: item.files[path] ?? null })).filter((f) => f.base !== f.local || !base.known)
+    const change = item.deleted ? ('deleted' as const) : item.baseRevision ? ('changed' as const) : ('new' as const)
+    const title = titleOf(item, titles)
+    const documentsChanged = Boolean(item.documents && (item.documents.upload.length || item.documents.remove.length))
+    return {
+      ref: item.ref,
+      kind: item.kind,
+      name: item.name,
+      title,
+      change,
+      line: itemLine({ kind: item.kind, name: item.name, title, change, changedPaths: base.known ? files.map((f) => f.path) : [], assetsChanged: Boolean(item.assets?.length) && base.known && !files.length, documentsChanged }),
+      state: item.state,
+      stateLabel: ITEM_STATE_WORD[item.state] ?? item.state,
+      error: item.error,
+      checks: checks.filter((c) => c.ref === item.ref || c.itemId === item.id).map((c) => ({ code: c.code, message: c.message })),
+      baseKnown: base.known,
+      files,
+      build: item.build ? { hasSource: item.build.hasSource } : null,
+      ...(item.assets ? { assets: item.assets.map((a) => ({ path: a.path, bytes: a.bytes })) } : {}),
+      ...(item.documents
+        ? {
+            documents: {
+              upload: item.documents.upload.map((d) => ({ fileName: documentPath(d.folder, d.fileName), bytes: d.bytes, change: d.replaces ? ('changed' as const) : ('new' as const), staged: d.staged !== false })),
+              remove: item.documents.remove.map((d) => ({ fileName: d.fileName })),
+            },
+          }
+        : {}),
+    }
+  })
+  const allTitles = Object.fromEntries(items.map((i) => [i.ref, i.title]))
+  const activity = activityOf(view, allTitles)
+  const orgStored = !!getSyncKey(project, 'organization')
+  const r = view.request
+  return {
+    data: {
+      request: { id: r.id, title: r.title, description: r.description, state: r.state, stateLabel: STATE_WORD[r.state] ?? r.state, createdAt: r.createdAt, updatedAt: r.updatedAt, mergedAt: r.mergedAt },
+      workspace: { name: link.workspaceName ?? null, organizationName: link.organizationName ?? null },
+      items,
+      activity,
+      checks: checks.filter((c) => !items.some((i) => i.ref === c.ref)).map((c) => ({ ref: c.ref, code: c.code, message: c.message })),
+      organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+    },
+    text: [
+      `${r.title} — ${STATE_WORD[r.state] ?? r.state} · ${plural(items.length, 'item')} · ${link.workspaceName ?? link.workspace}`,
+      ...(r.description ? [r.description] : []),
+      '',
+      ...items.flatMap((i) => [
+        `  ${i.line}  (${i.stateLabel})`,
+        ...(i.error ? [`      ! ${i.error}`] : []),
+        ...i.checks.map((c) => `      ! ${c.message}`),
+        ...(i.baseKnown ? [] : ['      · its base isn’t on this machine; its files are shown whole']),
+      ]),
+      '',
+      'Activity:',
+      ...activity.map((a) => `  ${a.at.slice(0, 16).replace('T', ' ')}  ${a.text}`),
+      ...(isOpen(r.state) ? ['', 'Apply it with `frontera local sync request apply`, or close it with `request close`.'] : []),
+    ].join('\n'),
+  }
+}
+
+async function apply(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const current = await currentView(project, link)
+  if (!current) throw new UsageError('no change request to apply', 'propose one with `frontera local sync push -t "<title>"`')
+  const { view, titles } = current
+  if (view.request.state === 'merged') throw new CliError(`“${view.request.title}” is already applied`, { code: 'CONFLICT', hint: 'propose new changes with `frontera local sync push -t "<title>"`' })
+  if (view.request.state === 'closed') throw new CliError(`“${view.request.title}” is closed`, { code: 'CONFLICT', hint: 'propose the changes again with `frontera local sync push -t "<title>"`' })
+  const allTitles = Object.fromEntries(view.items.map((i) => [i.ref, titleOf(i, titles)]))
+  const blueprint = view.items.some((i) => i.kind === 'blueprint')
+  const organizationKey = blueprint ? getSyncKey(project, 'organization') : null
+  if (blueprint && !organizationKey) {
+    throw new CliError('this change request changes the Blueprint, and applying it needs the organization key; none is stored for this project', { code: 'SYNC_NO_ORG_KEY', hint: 'connect again with `frontera local sync connect --workspace-key - --org-key -` (both keys on stdin), then apply' })
+  }
+  const migration = flagString(ctx, 'migration')?.trim()
+  let answer: View
+  try {
+    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, migration ? { migrationInstruction: migration } : {}, { organizationKey, timeoutMs: 15 * 60_000 })
+  } catch (err) {
+    if (err instanceof CliError && err.code === 'SYNC_CHECKS') {
+      const checks = checksOf(err.details)
+      throw new CliError(`not applied: ${plural(checks.length, 'check')} failed\n${checkLines(checks, allTitles).join('\n')}`, {
+        code: 'SYNC_APPLY_REFUSED',
+        hint: checks.some((c) => c.code === 'stale_base' || c.code === 'gone' || c.code === 'exists')
+          ? 'the workspace changed these items since they were proposed: pull and merge them (`frontera local sync pull <ref>`), push again, then apply'
+          : 'fix the items named and push again, then apply',
+        details: { checks },
+      })
+    }
+    throw err
+  }
+  const outcome = parseOutcome(answer.outcome)
+  recordRequest(project.root, link.workspace, answer, { applied: { ok: outcome.ok } })
+  if (!outcome.ok) {
+    // Fetch, so the project sees the workspace as it was put back. The request itself applies again as it is:
+    // the platform takes each put-back item's new revision as its base.
+    await fetchFor(project, link).catch(() => null)
+    throw new CliError(describeOutcome(outcome, allTitles).join('\n'), {
+      code: 'SYNC_APPLY_FAILED',
+      hint: /migration instruction/i.test(outcome.failure?.message ?? '') ? 'say what to do with existing records: apply again with `--migration "<instructions>"`' : 'once what failed is fixed, apply again (`frontera local sync request apply`); a fix in the project’s files is pushed first (`frontera local sync push`)',
+      details: { outcome, failed: outcome.failure ? { ref: outcome.failure.ref, title: allTitles[outcome.failure.ref] ?? outcome.failure.ref, message: outcome.failure.message } : null },
+    })
+  }
+  // The workspace now has the applied versions: fetch, and move each applied item's base to them.
+  let fetched: { changed: number; adopted: string[]; error: string | null } = { changed: 0, adopted: [], error: null }
+  try {
+    // A deletion shows only in a full read of the workspace's index (an incremental one lists no deletions).
+    const deleted = answer.items.filter((i) => i.deleted).map((i) => i.ref)
+    const result = await fetchFor(project, link, { full: deleted.length > 0 })
+    const { adopted } = adoptApplied(project.root, link.workspace, answer.items.map((i) => i.ref), snapshotItems(project.root, result.snapshot), readLock(project.root), new Date(), { deleted })
+    // An Agent's lessons were proposed for review: not proposed again; the next pull brings what reviewers approve.
+    adoptProposedLessons(project.root, link.workspace, answer.items.flatMap((i) => (i.ref.startsWith('lessons/') ? [i.ref.slice('lessons/'.length)] : [])))
+    fetched = { changed: result.changed.length, adopted, error: null }
+  } catch (err) {
+    fetched.error = (err as Error).message
+  }
+  // Documents applied are the project's copies of the workspace's now: recorded as a pull records them.
+  await recordAppliedDocuments(project, link, answer).catch(() => null)
+  return {
+    data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched },
+    text: [
+      `Applied “${answer.request.title}” to ${link.workspaceName ?? link.workspace}.`,
+      ...describeOutcome(outcome, allTitles),
+      '',
+      fetched.error ? `Could not fetch afterwards: ${fetched.error}. Run \`frontera local sync fetch\`.` : `Fetched: ${plural(fetched.adopted.length, 'item')} now match${fetched.adopted.length === 1 ? 'es' : ''} the workspace.`,
+    ].join('\n'),
+  }
+}
+
+/**
+ * After an Apply brought documents: each one uploaded is recorded against the
+ * workspace's new copy (the newest document of that name), and each taken off
+ * is forgotten, so the next push sees them as unchanged.
+ */
+async function recordAppliedDocuments(project: LocalProject, link: SyncLink, view: View): Promise<void> {
+  const items = view.items.filter((i) => i.kind === 'knowledge' && i.documents)
+  if (!items.length) return
+  const snapshot = readSnapshot(project.root)
+  const remote = snapshot ? snapshotItems(project.root, snapshot) : []
+  const api = platformFor(project, link)
+  for (const item of items) {
+    const id = remote.find((r) => r.ref === item.ref)?.id
+    if (!id) continue
+    const listed = await api.call<unknown>('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
+    const rows = (Array.isArray(listed) ? listed : []) as Array<{ id?: string; fileName?: string | null; createdAt?: string | null; folderId?: string | null }>
+    const folders = rows.some((r) => r.folderId) ? await readFolders({ get: (path) => api.call<unknown>('GET', path) }, id) : new Map<string, string>()
+    const pathOf = (r: { fileName?: string | null; folderId?: string | null }) => documentPath(r.folderId ? folders.get(r.folderId) : null, r.fileName ?? '')
+    const entries: Record<string, PulledDocument | null> = {}
+    for (const d of item.documents!.upload) {
+      const path = documentPath(d.folder, d.fileName)
+      const newest = rows.filter((r) => r.id && pathOf(r) === path).sort((a, b) => String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? '')))[0]
+      if (newest?.id) entries[path] = { sourceId: newest.id, sha256: d.sha256, bytes: d.bytes, at: new Date().toISOString() }
+    }
+    // A document taken off is forgotten by the copy it was, wherever it was filed.
+    const pulled = readPulledDocuments(project.root, link.workspace).bases[item.name] ?? {}
+    for (const d of item.documents!.remove) {
+      const at = Object.entries(pulled).find(([, was]) => was.sourceId === d.sourceId)?.[0]
+      entries[at ?? d.fileName] = null
+    }
+    recordPulledDocuments(project.root, link.workspace, item.name, entries)
+  }
+}
+
+async function close(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const kept = currentRequest(readRequests(project.root, link.workspace))
+  if (!kept || !isOpen(kept.state)) throw new UsageError('no open change request to close', 'see where it stands with `frontera local sync request`')
+  const view = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${kept.id}/close`, {})
+  recordRequest(project.root, link.workspace, view)
+  return { data: { closed: true, request: { id: view.request.id, title: view.request.title, state: view.request.state } }, text: `Closed “${view.request.title}”. The project’s files are unchanged; the next push opens a new change request.` }
+}
+
+const REQUEST_ACTIONS: Record<string, (ctx: CommandContext) => Promise<{ data: unknown; text: string }>> = { show, apply, close }
+
+export async function syncRequest(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
+  const action = ctx.positional[1] ?? 'show'
+  const run = REQUEST_ACTIONS[action]
+  if (!run) throw new UsageError(`unknown request action \`${action}\``, 'use show, apply or close')
+  return run(ctx)
+}