uniweb 0.12.32 → 0.12.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.32",
+  "version": "0.12.33",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.7.14",
     "@uniweb/kit": "0.9.18",
-    "@uniweb/runtime": "0.8.19"
+    "@uniweb/core": "0.7.14",
+    "@uniweb/runtime": "0.8.20"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.15",
-    "@uniweb/content-reader": "1.1.12",
-    "@uniweb/semantic-parser": "1.1.17"
+    "@uniweb/semantic-parser": "1.1.17",
+    "@uniweb/build": "0.14.16",
+    "@uniweb/content-reader": "1.1.12"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/backend/client.js

@@ -240,14 +240,21 @@ export class BackendClient {
     })
   }
 
-  /** GET /dev/site/content/pull/{uuid} — the content lane document. */
-  async pullSiteContent(uuid) {
-    return this.request(`/dev/site/content/pull/${encodeURIComponent(uuid)}`)
+  /**
+   * GET /dev/site/content/pull/{uuid} — the content lane document. Pass the
+   * last-seen ETag (opaque) to make it conditional: a match returns 304 (empty body).
+   */
+  async pullSiteContent(uuid, { etag } = {}) {
+    return this.request(`/dev/site/content/pull/${encodeURIComponent(uuid)}`, {
+      headers: etag ? { 'If-None-Match': etag } : {},
+    })
   }
 
   /** GET /dev/site/folder/pull/{uuid} — the folder lane (folder + record documents). */
-  async pullFolder(uuid) {
-    return this.request(`/dev/site/folder/pull/${encodeURIComponent(uuid)}`)
+  async pullFolder(uuid, { etag } = {}) {
+    return this.request(`/dev/site/folder/pull/${encodeURIComponent(uuid)}`, {
+      headers: etag ? { 'If-None-Match': etag } : {},
+    })
   }
 
   // ── Delivery: deploy + site publish ─────────────────────────────────────────────

package/src/commands/pull.js

@@ -32,18 +32,20 @@
  * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
  *
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
- * clear message. NOTE: the backend pull routes have not been exercised live; the
- * response-envelope extraction (extractDocument / splitCollectionsPull) is
- * deliberately tolerant and is the single point to adjust at the first live run.
+ * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
+ * `entities/<uuid>.json`); `readPullDocuments` reads the entity files out of it, with
+ * a tolerant JSON fallback (`extractDocument` / `splitCollectionsPull`). Verified live
+ * against the playground backend, 2026-06-17.
  */
 
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import {
   siteContentDocumentToProject,
   collectionsToProject,
   resolveCollectionsConfig,
+  readZip,
 } from '@uniweb/build/uwx'
 import { makeModelResolver } from './push.js'
 import { BackendClient } from '../backend/client.js'
@@ -76,6 +78,27 @@ function readYamlUuid(filePath) {
   }
 }
 
+// Conditional-pull ETag cache (gitignored `.uniweb/pull-cache.json`): the last ETag
+// seen per lane. The ETag is OPAQUE — cached and echoed verbatim in If-None-Match,
+// never parsed or recomputed (the backend owns the hash; the client treats it as a
+// token). A missing cache just means a full (unconditional) pull.
+function pullCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-cache.json')
+}
+function readPullCache(siteDir) {
+  try {
+    const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
+    return obj && typeof obj === 'object' ? obj : {}
+  } catch {
+    return {}
+  }
+}
+function writePullCache(siteDir, { content, folder }) {
+  const p = pullCachePath(siteDir)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ version: 1, content, folder }, null, 2) + '\n')
+}
+
 // Extract a single entity `$`-document from a pull response. Tolerant of a raw
 // document, or a `{ document }` / `{ entity }` envelope. (Adjust at live e2e.)
 export function extractDocument(payload) {
@@ -104,6 +127,46 @@ export function splitCollectionsPull(payload) {
   }
 }
 
+// Read a pull lane's bytes into entity `$`-documents. The backend serves a `.uwx`
+// (our Stored ZIP: `manifest.json` + `entities/<uuid>.json`); the entity files ARE the
+// documents. Falls back to a JSON body (a raw doc, a `{document}`/`{entity}` envelope,
+// or a list) so the lane survives a future envelope change. Returns an array (possibly
+// empty).
+export function readPullDocuments(buf) {
+  // `.uwx` ZIP — the local-file signature is "PK\x03\x04".
+  if (buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b) {
+    const docs = []
+    for (const [name, data] of readZip(buf)) {
+      if (name === 'manifest.json' || !name.endsWith('.json')) continue
+      try {
+        docs.push(JSON.parse(data.toString('utf8')))
+      } catch {
+        /* skip a non-document entry */
+      }
+    }
+    return docs
+  }
+  // JSON fallback — flatten any envelope splitCollectionsPull understands into a
+  // flat `$`-document list (a raw doc, a list, `{entities}`/`{documents}`, or
+  // `{folder, records}`).
+  let payload
+  try {
+    payload = JSON.parse(buf.toString('utf8'))
+  } catch {
+    return []
+  }
+  if (Array.isArray(payload)) return payload.map(extractDocument).filter(Boolean)
+  if (payload?.folder) return [payload.folder, ...(payload.records || [])].filter(Boolean)
+  const list = Array.isArray(payload?.entities)
+    ? payload.entities
+    : Array.isArray(payload?.documents)
+      ? payload.documents
+      : null
+  if (list) return list.map(extractDocument).filter(Boolean)
+  const single = extractDocument(payload)
+  return single ? [single] : []
+}
+
 /**
  * @param {string[]} args
  * @param {object} [deps] - injectable seams for testing: `fetch` (default global
@@ -141,10 +204,12 @@ export async function pull(args = [], deps = {}) {
     return { exitCode: 0 }
   }
 
-  // GET a pull lane via the client and parse it as JSON. `doRequest` is a thunk
-  // returning the client's Response promise. 404 → null (deleted / no access); any
-  // failure is reported and returns null (the lane is skipped, not fatal).
-  const getJson = async (label, doRequest) => {
+  // GET a pull lane via the client and return `{ docs, etag }` from its `.uwx` (ZIP)
+  // body — `readPullDocuments` reads the entity files out of it (JSON fallback). A
+  // conditional request whose ETag matches returns `{ notModified: true }` (304, empty
+  // body). `doRequest` is a thunk returning the client's Response promise. 404 / any
+  // failure → null (the lane is skipped, not fatal).
+  const getDocs = async (label, doRequest) => {
     info(`Pulling ${colors.bright}${label}${colors.reset} from ${colors.dim}${client.origin}${colors.reset} …`)
     let res
     try {
@@ -158,15 +223,21 @@ export async function pull(args = [], deps = {}) {
       note(`${label}: not found (404) — it was deleted, or you lack access.`)
       return null
     }
+    if (res.status === 304) {
+      note(`${label}: unchanged (304)`)
+      return { notModified: true }
+    }
     if (!res.ok) {
       error(`${label} pull failed: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) note("Credentials weren't accepted — supply a bearer with --token <bearer>.")
       return null
     }
     try {
-      return await res.json()
+      const etag = res.headers?.get?.('etag') ?? null
+      const docs = readPullDocuments(Buffer.from(await res.arrayBuffer()))
+      return { docs, etag }
     } catch (err) {
-      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      error(`Could not read the ${label} response: ${err.message}`)
       return null
     }
   }
@@ -176,25 +247,34 @@ export async function pull(args = [], deps = {}) {
   let records = 0
   let deleted = 0
 
-  // Lane 1 — content → config + pages/** + layout/**.
-  const siteDoc = extractDocument(
-    await getJson('content', () => client.pullSiteContent(siteContentUuid))
-  )
-  if (siteDoc) {
-    const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
-    pages += report.pages.length
-    sections += report.sections.length
-    deleted += report.deleted.length
+  // Conditional-pull cache: the last ETag seen per lane (opaque token — cached and
+  // echoed verbatim, never recomputed). Lives in the gitignored `.uniweb/`.
+  const cache = readPullCache(siteDir)
+  let etagContent = cache.content
+  let etagFolder = cache.folder
+
+  // Lane 1 — content → config + pages/** + layout/**. The .uwx carries a single
+  // entity (the site-content document). A 304 (unchanged) leaves local files as-is.
+  const content = await getDocs('content', () => client.pullSiteContent(siteContentUuid, { etag: etagContent }))
+  if (content && !content.notModified) {
+    const siteDoc = content.docs && (content.docs.find((d) => d?.info || d?.$model) || content.docs[0] || null)
+    if (siteDoc) {
+      const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
+      pages += report.pages.length
+      sections += report.sections.length
+      deleted += report.deleted.length
+    }
+    if (content.etag) etagContent = content.etag
   }
 
   // Lane 2 — folder → the folder + record files, keyed by the SAME site-content uuid
   // (the backend resolves the site's `@uniweb/folder` from it; the framework never
   // holds a folder uuid). Models are resolved by name (async) up front, so
-  // collectionsToProject keeps its synchronous contract.
+  // collectionsToProject keeps its synchronous contract. A 304 leaves files as-is.
   if (!noCollections) {
-    const payload = await getJson('collections', () => client.pullFolder(siteContentUuid))
-    if (payload) {
-      const { folderDoc, recordDocs } = splitCollectionsPull(payload)
+    const folder = await getDocs('collections', () => client.pullFolder(siteContentUuid, { etag: etagFolder }))
+    if (folder && !folder.notModified && folder.docs?.length) {
+      const { folderDoc, recordDocs } = splitCollectionsPull(folder.docs)
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
       for (const model of [...new Set(recordDocs.map((d) => d.$model).filter(Boolean))]) {
@@ -215,8 +295,12 @@ export async function pull(args = [], deps = {}) {
       for (const s of report.skipped) note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
       for (const w of report.warnings) note(`! ${w}`)
     }
+    if (folder?.etag) etagFolder = folder.etag
   }
 
+  // Persist the ETags so the next pull is conditional (304 when unchanged).
+  writePullCache(siteDir, { content: etagContent, folder: etagFolder })
+
   success(
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` + (deleted ? `, ${deleted} deleted` : '')
   )

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-17T20:00:18.933Z",
+  "generatedAt": "2026-06-18T03:42:23.549Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.15",
+      "version": "0.14.16",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -61,7 +61,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.19",
+      "version": "0.8.20",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.21",
+      "version": "0.4.22",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",