@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/lib/zip.test.ts

@@ -0,0 +1,110 @@
+import {describe, expect, it} from 'vitest'
+import {isZip, unzip, unzipText} from './zip'
+import {buildZip} from './zip.fixtures'
+
+/**
+ * A REAL Smartcat-format export archive: generated with the exact library and
+ * settings production uses — Smartcat.Fork.SharpZipLib 1.5.1, `ZipOutputStream
+ * { UseZip64 = On }`, streamed entries with `IsUnicodeText = true` (see
+ * ExportDocumentsProcessor.cs:1525 in the smartcat repo). Forced ZIP64 means
+ * every central-directory entry carries 0xFFFFFFFF size placeholders with the
+ * real values in ZIP64 extra fields — the format that a non-ZIP64 reader fails
+ * on (which silently degraded every batch to per-document fallback in v1).
+ */
+const SMARTCAT_ZIP64_ARCHIVE_B64 =
+  'UEsDBC0AAAgIAAeK6FzGlJGm//////////8iABQAcGFnZS9BYm91dC1hYmMxMjM0NShmci1GUikubG9janNvbgEAEAB8AAAAAAAA' +
+  'AGwAAAAAAAAAFYsxDsMgEAT/sjUukjiNS1fJGyIKgk8RNuEsOKREiL/7vNVqZ7Zhz7xTlkAFU8NvKC4F+Z99YV+/lOS5YIJ7+8v1' +
+  'Nt4H0qB3g6qefl4NG6kPCRIJBoVr9qQAD4qRYQ3E5Q/JOc2cVuWw3fYDUEsDBC0AAAgIAAeK6Fxyl2Ox//////////8iABQAcGFn' +
+  'ZS9Iw7ZtZS1kZWY2Nzg5MChmci1GUikubG9janNvbgEAEAB7AAAAAAAAAHEAAAAAAAAAFYsxDsIwEAT/srUjUZGQH1BQp0AuotwF' +
+  'WQQ7Op8lkOVv8QE+xmWr1exsxS5pZ9HAGWPFu8tzDPo5OqWlvDjqlTCCeD33w+XUrRa05lDMs8+94snmQ4NuDIeciixsA6YkG8E7' +
+  '6CwP1gPdft9IDN98+wNQSwMELQAACAgAB4roXGMJtzf//////////ysAFAByZXNwb25zaXZlSW1hZ2UvQWx0LTk5ODg3NzY2KGZy' +
+  'LUZSKS5sb2Nqc29uAQAQAEUAAAAAAAAAQQAAAAAAAACrViooyi9ILSrJTC1WsqpWqtAtTszLLKkEsVPyk0tzU/NKPFOUrJQsLS0s' +
+  'zM3NzHQTgUCptlZHqRSoDqgnOrYWAFBLAQIzAC0AAAgIAAeK6FzGlJGm//////////8iABQAAAAAAAAAAAAAAAAAAABwYWdlL0Fi' +
+  'b3V0LWFiYzEyMzQ1KGZyLUZSKS5sb2Nqc29uAQAQAHwAAAAAAAAAbAAAAAAAAABQSwECMwAtAAAICAAHiuhccpdjsf//////////' +
+  'IgAUAAAAAAAAAAAAAADAAAAAcGFnZS9Iw7ZtZS1kZWY2Nzg5MChmci1GUikubG9janNvbgEAEAB7AAAAAAAAAHEAAAAAAAAAUEsB' +
+  'AjMALQAACAgAB4roXGMJtzf//////////ysAFAAAAAAAAAAAAAAAhQEAAHJlc3BvbnNpdmVJbWFnZS9BbHQtOTk4ODc3NjYoZnIt' +
+  'RlIpLmxvY2pzb24BABAARQAAAAAAAABBAAAAAAAAAFBLBQYAAAAAAwADADUBAAAjAgAAAAA='
+
+function fromBase64(b64: string): Uint8Array {
+  const bin = atob(b64)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+describe('isZip', () => {
+  it('recognizes the PK magic', async () => {
+    const zip = await buildZip([{name: 'a.txt', content: 'hello'}])
+    expect(isZip(zip)).toBe(true)
+  })
+
+  it('rejects plain text and short payloads', () => {
+    expect(isZip(new TextEncoder().encode('{"units":[]}'))).toBe(false)
+    expect(isZip(new Uint8Array([0x50, 0x4b]))).toBe(false)
+  })
+})
+
+describe('unzip', () => {
+  it('parses a real Smartcat production-format archive (SharpZipLib, forced ZIP64)', async () => {
+    const bytes = fromBase64(SMARTCAT_ZIP64_ARCHIVE_B64)
+    expect(isZip(bytes)).toBe(true)
+
+    const entries = await unzipText(bytes)
+    expect(entries.map((e) => e.name)).toEqual([
+      'page/About-abc12345(fr-FR).locjson',
+      'page/Höme-def67890(fr-FR).locjson',
+      'responsiveImage/Alt-99887766(fr-FR).locjson',
+    ])
+    // Contents parse as LocJSON and carry the x-sanity correlation metadata.
+    const first = JSON.parse(entries[0].content)
+    expect(first.properties['x-sanity'].documentId).toBe('abc12345-eeee')
+    expect(first.units[0].target).toEqual(['Bonjour'])
+    const second = JSON.parse(entries[1].content)
+    expect(second.properties['x-sanity'].documentId).toBe('def67890-ffff')
+    expect(second.units[0].target).toEqual(['Mönde'])
+    const third = JSON.parse(entries[2].content)
+    expect(third.properties['x-sanity'].documentId).toBe('99887766-aaaa')
+  })
+
+  it('extracts stored entries', async () => {
+    const zip = await buildZip([
+      {name: 'page/About-abc12345(fr).locjson', content: '{"a":1}'},
+      {name: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+    const entries = await unzipText(zip)
+    expect(entries).toEqual([
+      {name: 'page/About-abc12345(fr).locjson', content: '{"a":1}'},
+      {name: 'page/Home-def67890(fr).locjson', content: '{"b":2}'},
+    ])
+  })
+
+  it('inflates deflate-compressed entries', async () => {
+    const long = 'translated content '.repeat(200)
+    const zip = await buildZip([{name: 'doc.locjson', content: long, method: 8}])
+    const entries = await unzipText(zip)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].content).toBe(long)
+  })
+
+  it('skips directory entries', async () => {
+    const zip = await buildZip([
+      {name: 'page/', content: ''},
+      {name: 'page/About.locjson', content: '{}'},
+    ])
+    const entries = await unzip(zip)
+    expect(entries.map((e) => e.name)).toEqual(['page/About.locjson'])
+  })
+
+  it('preserves non-ASCII entry names and contents', async () => {
+    const zip = await buildZip([{name: 'sida/Åh nej-abc12345(sv).locjson', content: '{"t":"översättning"}', method: 8}])
+    const entries = await unzipText(zip)
+    expect(entries[0].name).toBe('sida/Åh nej-abc12345(sv).locjson')
+    expect(entries[0].content).toBe('{"t":"översättning"}')
+  })
+
+  it('throws on payloads without an end-of-central-directory record', async () => {
+    await expect(unzip(new TextEncoder().encode('PK\x03\x04 not really a zip'))).rejects.toThrow(
+      /end-of-central-directory/,
+    )
+  })
+})

package/src/lib/zip.ts

@@ -0,0 +1,164 @@
+/**
+ * Minimal ZIP reader for Smartcat batch-export archives.
+ *
+ * Dependency-free by design (like the rest of the Function-side code): built on
+ * `DataView` + the global `DecompressionStream` (Node 18+ / browsers). Supports
+ * the two compression methods Smartcat archives use — stored (0) and deflate (8).
+ *
+ * ZIP64 is REQUIRED, not an edge case: Smartcat writes export archives with
+ * SharpZipLib's `UseZip64 = On` (forced), so central-directory size/offset
+ * fields hold `0xFFFFFFFF` placeholders with the real 64-bit values in each
+ * entry's ZIP64 extra field — even for tiny archives. Large archives
+ * additionally use the ZIP64 end-of-central-directory record.
+ */
+
+export interface ZipEntry {
+  /** Entry path inside the archive (folders separated by `/`). */
+  name: string
+  data: Uint8Array
+}
+
+const LOCAL_HEADER_SIG = 0x04034b50
+const CENTRAL_HEADER_SIG = 0x02014b50
+const EOCD_SIG = 0x06054b50
+const ZIP64_EOCD_SIG = 0x06064b50
+const ZIP64_EOCD_LOCATOR_SIG = 0x07064b50
+/** EOCD record is 22 bytes + an optional comment of up to 65535 bytes. */
+const EOCD_MIN_SIZE = 22
+/** ZIP64 EOCD locator is a fixed 20 bytes, sitting right before the classic EOCD. */
+const ZIP64_LOCATOR_SIZE = 20
+/** Placeholder meaning "the real value is in the ZIP64 extra field / record". */
+const U32_MAX = 0xffffffff
+const U16_MAX = 0xffff
+/** Extra-field header id of the ZIP64 extended information block. */
+const ZIP64_EXTRA_ID = 0x0001
+
+/** Whether the payload looks like a ZIP archive (`PK\x03\x04` magic). */
+export function isZip(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === 0x50 &&
+    bytes[1] === 0x4b &&
+    bytes[2] === 0x03 &&
+    bytes[3] === 0x04
+  )
+}
+
+/** Extracts all file entries (directories are skipped). */
+export async function unzip(bytes: Uint8Array): Promise<ZipEntry[]> {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const eocd = findEndOfCentralDirectory(view)
+  const entries: ZipEntry[] = []
+
+  let offset = eocd.centralDirectoryOffset
+  for (let i = 0; i < eocd.entryCount; i++) {
+    if (view.getUint32(offset, true) !== CENTRAL_HEADER_SIG) {
+      throw new Error(`Invalid ZIP: bad central directory entry at ${offset}`)
+    }
+    const method = view.getUint16(offset + 10, true)
+    let compressedSize: number = view.getUint32(offset + 20, true)
+    let uncompressedSize: number = view.getUint32(offset + 24, true)
+    const nameLength = view.getUint16(offset + 28, true)
+    const extraLength = view.getUint16(offset + 30, true)
+    const commentLength = view.getUint16(offset + 32, true)
+    let localHeaderOffset: number = view.getUint32(offset + 42, true)
+    const name = new TextDecoder().decode(bytes.subarray(offset + 46, offset + 46 + nameLength))
+
+    // ZIP64: any field at its 32-bit max is a placeholder; the real value lives
+    // in the entry's ZIP64 extra block, in a fixed order, holding ONLY the
+    // fields that overflowed (Smartcat's forced-ZIP64 writer always defers the
+    // sizes this way, even for small files).
+    if (compressedSize === U32_MAX || uncompressedSize === U32_MAX || localHeaderOffset === U32_MAX) {
+      const extraStart = offset + 46 + nameLength
+      const extraEnd = extraStart + extraLength
+      let p = extraStart
+      while (p + 4 <= extraEnd) {
+        const id = view.getUint16(p, true)
+        const size = view.getUint16(p + 2, true)
+        if (id === ZIP64_EXTRA_ID) {
+          let q = p + 4
+          if (uncompressedSize === U32_MAX) {
+            uncompressedSize = Number(view.getBigUint64(q, true))
+            q += 8
+          }
+          if (compressedSize === U32_MAX) {
+            compressedSize = Number(view.getBigUint64(q, true))
+            q += 8
+          }
+          if (localHeaderOffset === U32_MAX) {
+            localHeaderOffset = Number(view.getBigUint64(q, true))
+          }
+          break
+        }
+        p += 4 + size
+      }
+      if (compressedSize === U32_MAX || localHeaderOffset === U32_MAX) {
+        throw new Error(`Invalid ZIP: "${name}" needs ZIP64 sizes but has no ZIP64 extra field`)
+      }
+    }
+    offset += 46 + nameLength + extraLength + commentLength
+
+    if (name.endsWith('/')) continue // directory entry
+
+    // The local header repeats name/extra with its own lengths; the data
+    // follows it. Sizes come from the central directory (authoritative even
+    // when the local header deferred them to a data descriptor).
+    if (view.getUint32(localHeaderOffset, true) !== LOCAL_HEADER_SIG) {
+      throw new Error(`Invalid ZIP: bad local header for "${name}"`)
+    }
+    const localNameLength = view.getUint16(localHeaderOffset + 26, true)
+    const localExtraLength = view.getUint16(localHeaderOffset + 28, true)
+    const dataStart = localHeaderOffset + 30 + localNameLength + localExtraLength
+    const compressed = bytes.subarray(dataStart, dataStart + compressedSize)
+
+    entries.push({name, data: await decompress(method, compressed, name)})
+  }
+  return entries
+}
+
+/** Convenience: unzip and decode every file entry as UTF-8 text. */
+export async function unzipText(bytes: Uint8Array): Promise<{name: string; content: string}[]> {
+  const entries = await unzip(bytes)
+  const decoder = new TextDecoder()
+  return entries.map((e) => ({name: e.name, content: decoder.decode(e.data)}))
+}
+
+function findEndOfCentralDirectory(view: DataView): {
+  entryCount: number
+  centralDirectoryOffset: number
+} {
+  const lowest = Math.max(0, view.byteLength - EOCD_MIN_SIZE - 0xffff)
+  for (let i = view.byteLength - EOCD_MIN_SIZE; i >= lowest; i--) {
+    if (view.getUint32(i, true) !== EOCD_SIG) continue
+
+    let entryCount: number = view.getUint16(i + 10, true)
+    let centralDirectoryOffset: number = view.getUint32(i + 16, true)
+
+    // ZIP64: placeholder values defer to the ZIP64 EOCD record, found via the
+    // fixed-size locator that sits immediately before the classic EOCD.
+    if (entryCount === U16_MAX || centralDirectoryOffset === U32_MAX) {
+      const locator = i - ZIP64_LOCATOR_SIZE
+      if (locator < 0 || view.getUint32(locator, true) !== ZIP64_EOCD_LOCATOR_SIG) {
+        throw new Error('Invalid ZIP: ZIP64 values without a ZIP64 end-of-central-directory locator')
+      }
+      const zip64Eocd = Number(view.getBigUint64(locator + 8, true))
+      if (view.getUint32(zip64Eocd, true) !== ZIP64_EOCD_SIG) {
+        throw new Error('Invalid ZIP: bad ZIP64 end-of-central-directory record')
+      }
+      entryCount = Number(view.getBigUint64(zip64Eocd + 32, true))
+      centralDirectoryOffset = Number(view.getBigUint64(zip64Eocd + 48, true))
+    }
+    return {entryCount, centralDirectoryOffset}
+  }
+  throw new Error('Invalid ZIP: end-of-central-directory record not found')
+}
+
+async function decompress(method: number, data: Uint8Array, name: string): Promise<Uint8Array> {
+  if (method === 0) return data // stored
+  if (method === 8) {
+    // Copy into a fresh ArrayBuffer so the Blob sees exactly this entry's bytes.
+    const stream = new Blob([data.slice()]).stream().pipeThrough(new DecompressionStream('deflate-raw'))
+    return new Uint8Array(await new Response(stream).arrayBuffer())
+  }
+  throw new Error(`Unsupported ZIP compression method ${method} for "${name}"`)
+}

package/src/progress/core.ts

@@ -0,0 +1,387 @@
+import type {SmartcatProject, SmartcatDocument, RequestLogger} from '../smartcat/types'
+import {toSanityLanguage, type SmartcatLanguageMapping} from '../lib/languageMap'
+import {itemDocDeref} from '../lib/projectItems'
+import type {LogLine} from '../lib/log'
+
+/**
+ * Per-document, per-language, per-stage translation progress mirrored from
+ * Smartcat onto a `smartcat.translationProject`.
+ *
+ * This module is intentionally **dependency-free** (no DOM, no @sanity/* runtime)
+ * so it bundles cleanly into the thin `smartcat-progress` / `smartcat-import`
+ * Functions. All keys are deterministic, so repeated refreshes patch the same
+ * array members in place instead of churning `_key`s.
+ */
+
+export interface StageProgress {
+  /** Stable key for the Sanity array item (always set by `stagesFromDocument`). */
+  _key?: string
+  name: string
+  /** 0–100, rounded. */
+  percent: number
+}
+
+export interface TargetProgress {
+  _key: string
+  language: string
+  /** Smartcat target document id (`<fileGuid>_<languageNumber>`). */
+  smartcatDocumentId?: string
+  stages: StageProgress[]
+  /** All stages at 100%. */
+  complete: boolean
+  /** A locale variant has been built from this target (set by the browser). */
+  imported: boolean
+  syncedAt?: string
+}
+
+export interface DocProgress {
+  _key: string
+  sourceDocId: string
+  title?: string
+  targets: TargetProgress[]
+}
+
+/** Sanitizes an arbitrary string into a stable, Sanity-safe array `_key`. */
+export function keyify(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '-') || 'x'
+}
+
+/** Builds a progress target's `_key` from its document + language. */
+export function targetKey(sourceDocId: string, language: string): string {
+  return keyify(`${sourceDocId}__${language}`)
+}
+
+function clampPercent(value: number | undefined): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) return 0
+  return Math.max(0, Math.min(100, Math.round(value)))
+}
+
+/** Strips a `drafts.` prefix from a Sanity document id. */
+function stripDraft(id: string): string {
+  return id.replace(/^drafts\./, '')
+}
+
+function titleCase(value: string): string {
+  return value ? value.charAt(0).toUpperCase() + value.slice(1) : value
+}
+
+/**
+ * Builds a stage-id → display-name map from a project's `workflowStages`. On
+ * Smartcat, document-level stages carry only `{id, progress}` — the human name
+ * (`stageType`, e.g. "translation") lives on the project-level stages.
+ */
+export function buildStageNameMap(scProject: SmartcatProject): Map<string, string> {
+  const map = new Map<string, string>()
+  ;(scProject.workflowStages ?? []).forEach((stage, i) => {
+    if (stage.id) map.set(stage.id, titleCase(stage.stageType || stage.stageName || `Stage ${i + 1}`))
+  })
+  return map
+}
+
+/** Maps a Smartcat document's workflow stages to display-ready stage progress. */
+export function stagesFromDocument(
+  doc: SmartcatDocument,
+  stageNames: Map<string, string>,
+): StageProgress[] {
+  const stages = doc.workflowStages ?? []
+  return stages.map((stage, i) => ({
+    _key: stage.id || `s${i}`,
+    name:
+      (stage.id && stageNames.get(stage.id)) ||
+      titleCase(stage.stageType || stage.stageName || `Stage ${i + 1}`),
+    percent: clampPercent(stage.progress),
+  }))
+}
+
+/** A target is complete when it has stages and every one is at 100%. */
+export function isTargetComplete(stages: StageProgress[]): boolean {
+  return stages.length > 0 && stages.every((s) => s.percent >= 100)
+}
+
+/**
+ * Whether a target has any content confirmed at any stage — i.e. there is
+ * something worth importing. Used to gate `mode=confirmed` downloads so we skip
+ * targets with nothing confirmed yet (which would otherwise come back as source).
+ */
+export function hasConfirmedContent(stages: StageProgress[]): boolean {
+  return stages.some((s) => s.percent > 0)
+}
+
+/** Average completion across a target's stages (0–100). */
+export function targetPercent(stages: StageProgress[]): number {
+  if (stages.length === 0) return 0
+  return Math.round(stages.reduce((sum, s) => sum + s.percent, 0) / stages.length)
+}
+
+/** A project item we correlate Smartcat documents back to. */
+export interface ProjectItem {
+  _id: string
+  title?: string
+}
+
+/**
+ * Extracts the 8-char source-id prefix Smartcat preserves in a document's
+ * filename (built as `<title>-<idPrefix>.locjson`). Used to correlate a Smartcat
+ * document back to a Sanity source document.
+ *
+ * The prefix is always the final 8 characters before the extension, so take the
+ * tail rather than splitting on a dash — the title or the id prefix itself can
+ * contain dashes (e.g. a custom id like `demo-pdpA` → prefix `demo-pdp`), which
+ * would make a last-dash split return the wrong fragment.
+ *
+ * Only a literal `.locjson` extension is stripped (Smartcat's API often returns
+ * the name without it). A generic strip-after-last-dot would eat the tail of any
+ * DOTTED title — e.g. micro-copy keys like `aiAssistantModal.resetChat-11AKrV8G`
+ * — leaving the wrong 8 chars, so those documents silently never correlate,
+ * never import, and re-syncs duplicate them instead of updating.
+ */
+export function sourceIdPrefix(doc: SmartcatDocument): string {
+  const base = doc.name || doc.filename || doc.fullPath || ''
+  const leaf = base.split('/').pop() ?? ''
+  const noExt = leaf.replace(/\.locjson$/i, '')
+  return noExt.slice(-8)
+}
+
+/**
+ * Builds the full progress array from a freshly fetched Smartcat project and the
+ * project's items — independent of any export-time skeleton, so it works for
+ * projects exported before progress tracking existed.
+ *
+ * Documents are correlated to items by the 8-char id prefix in their filename;
+ * `imported` flags are carried over from the previous progress (by source doc +
+ * language) so importing isn't forgotten on refresh.
+ *
+ * `mappings` invert Smartcat's returned target codes back to Sanity ids, so all
+ * stored progress uses Sanity locale tags. When omitted, codes pass through
+ * unchanged (identity) — keeping legacy projects working.
+ */
+export function buildProgress(
+  items: ProjectItem[],
+  scProject: SmartcatProject,
+  previous: DocProgress[] | undefined,
+  now: string,
+  mappings?: SmartcatLanguageMapping[],
+): DocProgress[] {
+  const stageNames = buildStageNameMap(scProject)
+
+  const importedSet = new Set<string>()
+  // Titles are computed Sanity-native in the Studio and shipped on the outbox, so
+  // they may not be re-derivable server-side. Carry the previously-stored title
+  // forward so a progress sync (which only has the raw `doc.title`) can't clobber
+  // it with an "Untitled" for types that have no literal title field.
+  const titleByDoc = new Map<string, string>()
+  for (const doc of previous ?? []) {
+    if (doc.title) titleByDoc.set(doc.sourceDocId, doc.title)
+    for (const target of doc.targets) {
+      if (target.imported) importedSet.add(`${doc.sourceDocId}__${target.language}`)
+    }
+  }
+
+  const itemByPrefix = new Map<string, ProjectItem>()
+  for (const item of items) itemByPrefix.set(stripDraft(item._id).slice(0, 8), item)
+
+  const byDoc = new Map<string, DocProgress>()
+  for (const scDoc of scProject.documents ?? []) {
+    if (!scDoc.targetLanguage) continue
+    const item = itemByPrefix.get(sourceIdPrefix(scDoc))
+    if (!item) continue
+
+    // Store the Sanity locale tag, not Smartcat's code.
+    const language = toSanityLanguage(mappings, scDoc.targetLanguage)
+
+    let docProgress = byDoc.get(item._id)
+    if (!docProgress) {
+      const title = item.title || titleByDoc.get(item._id)
+      docProgress = {_key: targetKey(item._id, 'doc'), sourceDocId: item._id, title, targets: []}
+      byDoc.set(item._id, docProgress)
+    }
+    const stages = stagesFromDocument(scDoc, stageNames)
+    docProgress.targets.push({
+      _key: targetKey(item._id, language),
+      language,
+      smartcatDocumentId: scDoc.id,
+      stages,
+      complete: isTargetComplete(stages),
+      imported: importedSet.has(`${item._id}__${language}`),
+      syncedAt: now,
+    })
+  }
+
+  // Preserve item order; sort each doc's targets by language for stable display.
+  const result: DocProgress[] = []
+  for (const item of items) {
+    const docProgress = byDoc.get(item._id)
+    if (!docProgress) continue
+    docProgress.targets.sort((a, b) => a.language.localeCompare(b.language))
+    result.push(docProgress)
+  }
+  return result
+}
+
+export interface CompletionSummary {
+  /** Total (document × language) targets. */
+  total: number
+  /** Targets whose stages are all at 100%. */
+  complete: number
+  /** Targets a variant has been built for. */
+  imported: number
+  /** True when every target is complete and imported (and there is ≥1 target). */
+  allDone: boolean
+  /** True when at least one stage shows any progress. */
+  anyProgress: boolean
+}
+
+/** Summarizes a progress array for status decisions and the dashboard. */
+export function summarizeCompletion(progress: DocProgress[]): CompletionSummary {
+  let total = 0
+  let complete = 0
+  let imported = 0
+  let anyProgress = false
+  for (const doc of progress) {
+    for (const target of doc.targets) {
+      total++
+      if (target.complete) complete++
+      if (target.imported) imported++
+      if (target.stages.some((s) => s.percent > 0)) anyProgress = true
+    }
+  }
+  return {
+    total,
+    complete,
+    imported,
+    allDone: total > 0 && complete === total && imported === total,
+    anyProgress,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Function-side orchestration: refresh progress from Smartcat
+// ---------------------------------------------------------------------------
+
+/** Minimal structural subset of @sanity/client used by the progress refresh. */
+export interface SanityLikeClient {
+  fetch<T = unknown>(query: string, params?: Record<string, unknown>): Promise<T>
+  patch(id: string): {
+    set(attrs: Record<string, unknown>): {commit(): Promise<unknown>}
+  }
+}
+
+/** Structural subset of SmartcatClient the progress refresh needs. */
+export interface SmartcatProgressClient {
+  getProject(projectId: string): Promise<SmartcatProject>
+  /** Optional: trace every HTTP call so a timeout/error reaches the functionLog. */
+  setRequestLogger?(logger: RequestLogger): void
+}
+
+export interface RunProgressSyncOptions {
+  sanity: SanityLikeClient
+  smartcat: SmartcatProgressClient
+  /** `_id` of the `smartcat.translationProject` to refresh. */
+  projectId: string
+  now?: () => string
+}
+
+export interface RunProgressSyncResult {
+  summary: CompletionSummary
+  /** Set when the Smartcat fetch failed (e.g. timed out); the run was recorded, not thrown. */
+  error?: string
+}
+
+const PROGRESS_QUERY = `*[_id == $id][0]{
+  _id,
+  status,
+  smartcatProjectId,
+  smartcatLanguages[]{sanityId, smartcatLanguage},
+  "items": items[]{ "doc": ${itemDocDeref('{_id}')} },
+  progress[]{_key, sourceDocId, title, targets[]{_key, language, smartcatDocumentId, stages, complete, imported, syncedAt}}
+}`
+
+interface ProgressProjectData {
+  _id: string
+  status?: string
+  smartcatProjectId?: string
+  smartcatLanguages?: SmartcatLanguageMapping[]
+  items?: {doc: {_id: string} | null}[]
+  progress?: DocProgress[]
+}
+
+/** Resolves a project's referenced items into the lightweight shape we correlate on. */
+export function itemsFromProject(project: {
+  items?: {doc: {_id: string} | null}[]
+}): ProjectItem[] {
+  return (project.items ?? [])
+    .map((i) => i?.doc)
+    .filter((d): d is {_id: string} => Boolean(d))
+    .map((d) => ({_id: d._id}))
+}
+
+/**
+ * Thin progress step run by the `smartcat-progress` Function: fetches the
+ * Smartcat project and mirrors its per-stage progress onto the project's
+ * `progress` array. Read-only with respect to Smartcat — it never downloads or
+ * creates variants, so it is cheap to run on every dashboard page load.
+ */
+export async function runProgressSync(
+  options: RunProgressSyncOptions,
+): Promise<RunProgressSyncResult> {
+  const {sanity, smartcat, projectId, now = () => new Date().toISOString()} = options
+
+  const project = await sanity.fetch<ProgressProjectData | null>(PROGRESS_QUERY, {id: projectId})
+  if (!project) throw new Error(`Translation project ${projectId} not found`)
+  if (!project.smartcatProjectId) {
+    throw new Error('Project has no smartcatProjectId — export it first')
+  }
+
+  const timestamp = now()
+
+  // Trace HTTP failures into a functionLog so a timeout/error surfaces in the UI.
+  // Successful calls are left unlogged: this Function runs on every page load, and
+  // functionLog is shared with export/import — writing it on every success would
+  // wipe a useful export/import log.
+  const log: LogLine[] = []
+  smartcat.setRequestLogger?.(({method, path, status, body}) => {
+    if (status >= 200 && status < 300) return
+    log.push({
+      level: 'error',
+      message: status ? `Error ${status} while performing ${method} ${path}` : `${method} ${path} did not complete`,
+    })
+    if (body) log.push({level: 'error', indent: true, message: body})
+  })
+
+  try {
+    const scProject = await smartcat.getProject(project.smartcatProjectId)
+    const progress = buildProgress(
+      itemsFromProject(project),
+      scProject,
+      project.progress,
+      timestamp,
+      project.smartcatLanguages,
+    )
+    const summary = summarizeCompletion(progress)
+
+    const patch: Record<string, unknown> = {progress, progressSyncedAt: timestamp, lastError: null}
+    // Gentle one-way nudge: once Smartcat reports any work, reflect it in the badge.
+    // Completion remains owned by the import flow.
+    if (project.status === 'sent' && summary.anyProgress) {
+      patch.status = 'translating'
+    }
+
+    await sanity.patch(projectId).set(patch).commit()
+
+    return {summary}
+  } catch (err) {
+    // Record the failure and return instead of throwing: a throw would let the
+    // platform retry, and a timed-out fetch has nothing transient to gain. Leave
+    // the existing `progress` untouched (no zeroing-out) and only stamp the error
+    // plus a fresh `progressSyncedAt`, which releases the UI refresh spinner and
+    // makes the log land where the dashboard reads it.
+    const message = err instanceof Error ? err.message : String(err)
+    if (!log.some((l) => l.level === 'error')) log.push({level: 'error', message})
+    await sanity
+      .patch(projectId)
+      .set({lastError: message, functionLog: JSON.stringify(log), progressSyncedAt: timestamp})
+      .commit()
+      .catch(() => {})
+    return {summary: summarizeCompletion(project.progress ?? []), error: message}
+  }
+}

package/src/progress/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Public entry for the `./progress` subpath. The implementation lives in
+ * `./core` so the other build entries (`./export`, `./import`) can import the
+ * shared helpers via a deep path without pkg-utils treating one entry as an
+ * external of another.
+ */
+export * from './core'