uniweb 1.24.6 → 1.24.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.24.6",
3
+ "version": "1.24.8",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
+ "@uniweb/content-writer": "~1.3.1",
44
45
  "@uniweb/core": "~1.5.1",
45
- "@uniweb/semantic-parser": "~1.13.0",
46
46
  "@uniweb/schemas": "~1.6.7",
47
- "@uniweb/content-writer": "~1.3.1"
47
+ "@uniweb/semantic-parser": "~1.13.0"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.13.2",
51
- "@uniweb/semantic-parser": "~1.13.0",
52
- "@uniweb/content-reader": "~1.5.7"
50
+ "@uniweb/build": "~1.13.4",
51
+ "@uniweb/content-reader": "~1.5.7",
52
+ "@uniweb/semantic-parser": "~1.13.0"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -43,6 +43,8 @@ uniweb <command> --help # exact flags, always current — no side effects
43
43
  uniweb doctor # diagnose project configuration (--fix to repair)
44
44
  ```
45
45
 
46
+ Commands are written `uniweb <command>` throughout this guide. Without a global install, run them in the project as `npx uniweb <command>`.
47
+
46
48
  `uniweb inspect` is the important one for content. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
47
49
 
48
50
  `uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, when you come back to the project, before you push, publish or deploy, and after a command refuses: it changes nothing, opens with what the site is — synced where, live where — and ends with the commands to run, in order (`--json` for a script).
@@ -3076,6 +3078,8 @@ Running `extract` before a build is the usual first mistake — it reads the com
3076
3078
 
3077
3079
  An override key is the page's route and the section's id (`cta` for `2-cta.md`); a page's own title, label, description and keywords are `/pricing:_meta`, and in `locales/records/` a record is named by its manifest context (`std/article/launch`).
3078
3080
 
3081
+ **An entry can be flagged `outdated`:** `{ "default": "Acerca de PandaWatch", "outdated": { "/about:hero": "About PandaWatch" } }`. The source was edited a little, and the old translation stays until someone reviews it, so it still shows, and `uniweb i18n status` lists it. An edit in the Uniweb app does this, and so does one in a file, at `uniweb i18n sync` or at the push. To finish it, replace the entry with the new translation as a plain string, or with the same words as a plain string if they still hold. An edit that shares under half its words with the old text keeps nothing, and neither does a page title, an image's alt text or a data block's string: those show the source until they are translated. **`locales/_kept.json`** holds what the app keeps for a section that no file has a place for. A pull writes it and a push sends it back, so commit it and leave it alone.
3082
+
3079
3083
  *Free-form bodies* — when a language needs different structure, different images, or copy rewritten rather than translated. The file replaces one section's content:
3080
3084
 
3081
3085
  ```
@@ -52,7 +52,7 @@
52
52
  */
53
53
 
54
54
  import { readFileSync } from 'node:fs'
55
- import { join } from 'node:path'
55
+ import { join, relative } from 'node:path'
56
56
  import { execFileSync } from 'node:child_process'
57
57
 
58
58
  import {
@@ -65,6 +65,7 @@ import {
65
65
  import { computeFoundationDigest } from '../utils/code-upload.js'
66
66
  import { isNonInteractive } from '../utils/interactive.js'
67
67
  import { readOrgFlag } from '../utils/args.js'
68
+ import { repoOf, uncommittedPaths } from '../utils/sync-point.js'
68
69
  import { belongsToScope } from '../utils/registry-orgs.js'
69
70
  import { writeJsonPreservingStyle } from '../utils/json-file.js'
70
71
  import {
@@ -150,6 +151,33 @@ export function resolveLocalExtensions(siteDir, siteYml) {
150
151
  return out
151
152
  }
152
153
 
154
+
155
+ /**
156
+ * ⭐ WHAT A RELEASE WRITES, A PUSH COMMITS (`commitWriteBacks`). Bringing local code along writes
157
+ * into it: the scope it registered under into its name (`main.js`), the next version into its
158
+ * `package.json`. These are those files, relative to the site, where git holds them as they
159
+ * stand. Asked before the release, so a file holding the person's own edits stays theirs to commit.
160
+ *
161
+ * ⛔ Until 2026-10-30 they were left out, so a first push, even with `--commit`, left the project
162
+ * with `main.js` changed. Measured from a fresh scaffold, on every template tried.
163
+ *
164
+ * @param {string} siteDir
165
+ * @param {object} siteYml - parsed site.yml
166
+ * @returns {Promise<string[]>}
167
+ */
168
+ export async function filesAReleaseWrites(siteDir, siteYml) {
169
+ const repo = repoOf(siteDir)
170
+ if (!repo?.head) return []
171
+ const local = [resolveLocalFoundation(siteDir, siteYml), ...resolveLocalExtensions(siteDir, siteYml)].filter(Boolean)
172
+ const files = []
173
+ for (const { dir } of local) {
174
+ const main = await readFoundationName(dir).then((r) => r.mainFile, () => null)
175
+ if (main) files.push(main)
176
+ files.push(join(dir, 'package.json'))
177
+ }
178
+ return files.map((file) => relative(siteDir, file)).filter((file) => uncommittedPaths(repo, [file])?.length === 0)
179
+ }
180
+
153
181
  /**
154
182
  * The foundation's scoped catalog name (`@org/name`): its name — `main.js`'s
155
183
  * `name`, else package.json's, the one rule the build reads for the schema
@@ -70,8 +70,12 @@ import {
70
70
  siteContentRemovals,
71
71
  recordRemovals,
72
72
  cleanedRecord,
73
+ documentRows,
74
+ documentSourceLocale,
75
+ sectionsChangedSince,
73
76
  SYNC_STORE_FILE
74
77
  } from '@uniweb/build/uwx'
78
+ import { keepEditedTranslations, rowsWantTranslation, formatKeptTranslations } from '@uniweb/build/i18n'
75
79
 
76
80
  // First entity `$`-document out of a `.uwx` we produced or the backend served.
77
81
  // Deliberately NOT pull.js's `readPullDocuments`: that one is tolerant of JSON
@@ -160,7 +164,8 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
160
164
  const localDoc = entityDocFromUwx(localBuffer)
161
165
  if (!remoteDoc || !localDoc) return []
162
166
  return describeSiteDiff(
163
- diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir, client.origin))
167
+ diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir, client.origin)),
168
+ { label: (unit) => unitFilesOf(siteDir, unit)[0] ?? unit }
164
169
  )
165
170
  } catch {
166
171
  return []
@@ -1062,6 +1067,15 @@ export function uncommittedContent(siteDir, { verb = 'push' } = {}) {
1062
1067
  }
1063
1068
  }
1064
1069
 
1070
+ /**
1071
+ * Whether a publish may commit its record, `deploy.yml`: git holds it as it stands, or it isn't
1072
+ * there yet. A file holding the person's own edits stays theirs to commit.
1073
+ */
1074
+ export function deployRecordAtRest(siteDir) {
1075
+ const repo = repoOf(siteDir)
1076
+ return Boolean(repo?.head) && uncommittedPaths(repo, ['deploy.yml'])?.length === 0
1077
+ }
1078
+
1065
1079
  /** Says what `commitWriteBacks` committed, or that it could not. */
1066
1080
  export function reportWriteBacks(made, { note }) {
1067
1081
  if (!made) return
@@ -1100,9 +1114,16 @@ export function commitSiteContent(siteDir, { message }) {
1100
1114
  * ⛔ Until 2026-10-18 they were left to the person to commit, and a project pushed once and
1101
1115
  * not committed after had no `sync.json` in the history its clones got.
1102
1116
  *
1117
+ * @param {string} siteDir
1118
+ * @param {string} backend
1119
+ * @param {object} [o]
1120
+ * @param {boolean} [o.complete] - every lane landed, so the commit is this copy's sync point
1121
+ * @param {string[]} [o.released] - what the release wrote into local code (`filesAReleaseWrites`)
1122
+ * @param {string[]} [o.only] - these files alone, for a pull or a publish's record: what else
1123
+ * differs under the site is the person's, not a push's
1103
1124
  * @returns {{ commit: string, paths: string[] } | { error: string } | null}
1104
1125
  */
1105
- export function commitWriteBacks(siteDir, backend, { complete = false } = {}) {
1126
+ export function commitWriteBacks(siteDir, backend, { complete = false, released = [], only = null } = {}) {
1106
1127
  const repo = repoOf(siteDir)
1107
1128
  if (!repo?.head || mergeInProgress(repo)) return null
1108
1129
  let host = 'backend'
@@ -1121,7 +1142,7 @@ export function commitWriteBacks(siteDir, backend, { complete = false } = {}) {
1121
1142
  // ⭐ Marked with the backend and the site, so a pull reads the commit a lane names through
1122
1143
  // it (`recordedAfter`, utils/sync-point.js): the ids written back are what the backend holds.
1123
1144
  const site = readBackendState(siteDir, backend).site?.uuid
1124
- const made = commitRoots(repo, [...sentRoots(siteDir), SYNC_STORE_FILE], {
1145
+ const made = commitRoots(repo, only || [...sentRoots(siteDir), SYNC_STORE_FILE, ...released], {
1125
1146
  message: `Record what ${backend} gave the site${site ? `\n\n${RECORDED_TRAILER}: ${backend} ${site}` : ''}`,
1126
1147
  identity
1127
1148
  })
@@ -1712,7 +1733,7 @@ export function refuseUnsendableRecords(refusals, { error, note }) {
1712
1733
  if (!refusals?.length) return false
1713
1734
  const n = refusals.length
1714
1735
  error(
1715
- `${n === 1 ? 'A record' : `${n} records`} cannot be pushed as written — no content was sent.`
1736
+ `${n === 1 ? 'One item' : `${n} items`} cannot be pushed as written — no content was sent.`
1716
1737
  )
1717
1738
  for (const r of refusals) note(` ${r}`)
1718
1739
  return true
@@ -1828,6 +1849,38 @@ export async function recoverUnbankedIdentity({ client, siteDir, pkg, note }) {
1828
1849
  return again
1829
1850
  }
1830
1851
 
1852
+ /**
1853
+ * ⭐ A SOURCE EDIT IN A FILE KEEPS ITS TRANSLATION UNTIL SOMEONE REVIEWS IT, as one in the app does
1854
+ * (`keepEditedTranslations`), and the package goes again with it. The text it was made from is in the
1855
+ * document the push is about to change: one read, made only when a section this copy changed has a row
1856
+ * with no translation. What it finds goes into the translation files, where the next push reads it and a
1857
+ * person sees it, and `commitWriteBacks` commits it.
1858
+ *
1859
+ * Best-effort: with nothing read, the row falls back to the source as any row with no translation does.
1860
+ *
1861
+ * @returns {Promise<boolean>} whether to build the package again
1862
+ */
1863
+ export async function keepTranslationsOfEdits({ client, siteDir, pkg, note }) {
1864
+ const uuid = readBackendState(siteDir, client.origin).site?.uuid
1865
+ const local = uuid && pkg?.siteContent ? entityDocFromUwx(pkg.siteContent.buffer) : null
1866
+ if (!local) return false
1867
+ const sourceLocale = documentSourceLocale(local)
1868
+ const changed = sectionsChangedSince(local, readUnitBases(siteDir, client.origin).local, sourceLocale)
1869
+ const current = documentRows(local, sourceLocale, (record) => changed.has(record))
1870
+ if (!rowsWantTranslation(siteDir, current, { sourceLocale })) return false
1871
+ try {
1872
+ const res = await client.pullSiteContent(uuid)
1873
+ if (!res?.ok) return false
1874
+ const stored = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
1875
+ if (!stored) return false
1876
+ const said = formatKeptTranslations(keepEditedTranslations(siteDir, documentRows(stored, sourceLocale), current, { sourceLocale }))
1877
+ for (const line of said) note(line)
1878
+ return said.length > 0
1879
+ } catch {
1880
+ return false
1881
+ }
1882
+ }
1883
+
1831
1884
  export function readUnitBases(siteDir, backend) {
1832
1885
  const v = readMap(siteDir, backend, 'unitBases')
1833
1886
  return { local: v.local || {}, remote: v.remote || {} }
@@ -1980,12 +2033,17 @@ export async function entityHashes(siteDir, backend = null, { declarations, fiel
1980
2033
  * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
1981
2034
  * site whose foundation is not in the project (a clone's) can be re-banked offline
1982
2035
  */
1983
- export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null } = {}) {
2036
+ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null, contentTaken = false } = {}) {
1984
2037
  // ⛔ With the keys this deployment's Sections take, when the caller has them (`deploymentFields`):
1985
2038
  // they shape the document the next push sends (`typed_by_data_key`, `og_title`), so a hash banked
1986
2039
  // without them marks a clone's first push as changed. Until 2026-09-26 a pull banked none.
1987
2040
  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields })
1988
2041
  writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs), pkg.applied || {})
2042
+ // ⭐ And the local unit base, from what this copy would send for the content the pull took, so a
2043
+ // refusal after a pull can tell this copy's edits from the backend's. ⛔ Until 2026-10-30 a pull
2044
+ // left it empty, and the next refusal said "No record of your last sync" just after one.
2045
+ const sendsNow = contentTaken && pkg.siteContent ? entityDocFromUwx(pkg.siteContent.buffer) : null
2046
+ if (sendsNow) writeUnitBases(siteDir, backend, { local: computeUnitHashes(sendsNow) })
1989
2047
  // ⭐ And the identity of the records' list items, from the documents the pull just took:
1990
2048
  // the files it wrote hold the stored items in stored order, so the emit over them pairs
1991
2049
  // with each document item for item.
@@ -561,9 +561,10 @@ export async function checkFoundationSupports({
561
561
  }
562
562
  }
563
563
 
564
+ // A note, not a warning: nothing is broken (above), and `uniweb status` asks for a read of each warning.
564
565
  issues.push({
565
566
  id,
566
- type: 'warn',
567
+ type: 'info',
567
568
  foundation: foundationName,
568
569
  message: hasDeclaration
569
570
  ? `${foundationName} builds against ${list} but does not declare ${missing.length === 1 ? 'it' : 'them'} in uniweb.supports`
@@ -572,7 +573,7 @@ export async function checkFoundationSupports({
572
573
  fixable: true,
573
574
  })
574
575
 
575
- warn(`[${id}] ${foundationName} builds against ${list}, not in ${folderName}/package.json`)
576
+ info(`[${id}] ${foundationName} builds against ${list}, not in ${folderName}/package.json`)
576
577
  log(` The build already publishes ${colors.dim}${derived.join(', ')}${colors.reset}, so nothing is missing on the wire.`)
577
578
  log(` Declaring it matters when a service is named by a computed value — the`)
578
579
  log(` build cannot see those, and yours is the only place they can be added.`)
@@ -1083,14 +1084,17 @@ export async function checkSiteAddress({ sitePath, siteName, siteYml, workspaceD
1083
1084
  }
1084
1085
  }
1085
1086
 
1087
+ // ⭐ A warning once a host is named that does not state it. With none named yet the site may well
1088
+ // go to one that does, so it is a note. ⛔ Until 2026-10-30 every new project got the warning,
1089
+ // and an agent told to read it had no address to give but an invented one.
1086
1090
  const id = 'site-address-unknown'
1087
1091
  issues.push({
1088
1092
  id,
1089
- type: 'warn',
1093
+ type: host ? 'warn' : 'info',
1090
1094
  site: siteName,
1091
1095
  message: 'The site states no address: no canonical URLs, no sitemap.xml, a root-relative llms.txt and og:image'
1092
1096
  })
1093
- warn(`[${id}] Nothing states where this site is served`)
1097
+ ;(host ? warn : info)(`[${id}] Nothing states where this site is served`)
1094
1098
  log(` Set ${colors.green}seo.origin${colors.reset} in site.yml — the origin it is served from, e.g. https://example.com`)
1095
1099
  log(` ${colors.dim}A host that states it needs none: the GitHub Pages workflow \`uniweb add ci\` writes, Netlify, Vercel.${colors.reset}`)
1096
1100
  log(` ${colors.dim}${without}${colors.reset}`)
@@ -889,6 +889,7 @@ async function runStatusMissing(siteRoot, config, locale, options = {}) {
889
889
 
890
890
  // Collect missing strings from all requested locales
891
891
  const allMissing = []
892
+ const allOutdated = []
892
893
  const byLocale = {}
893
894
 
894
895
  for (const loc of localesToCheck) {
@@ -897,11 +898,13 @@ async function runStatusMissing(siteRoot, config, locale, options = {}) {
897
898
  total: result.total,
898
899
  translated: result.valid.length,
899
900
  missing: result.missing.length,
901
+ outdated: result.outdated?.length ?? 0,
900
902
  coverage:
901
903
  result.total > 0
902
904
  ? Math.round((result.valid.length / result.total) * 100)
903
905
  : 100
904
906
  }
907
+ for (const entry of result.outdated || []) allOutdated.push({ locale: loc, ...entry })
905
908
 
906
909
  // Add locale info to each missing entry
907
910
  for (const entry of result.missing) {
@@ -916,7 +919,8 @@ async function runStatusMissing(siteRoot, config, locale, options = {}) {
916
919
  if (outputJson) {
917
920
  const output = {
918
921
  locales: byLocale,
919
- missing: allMissing
922
+ missing: allMissing,
923
+ outdated: allOutdated
920
924
  }
921
925
  log(JSON.stringify(output, null, 2))
922
926
  return
@@ -927,11 +931,21 @@ async function runStatusMissing(siteRoot, config, locale, options = {}) {
927
931
 
928
932
  // Show summary per locale
929
933
  for (const [loc, info] of Object.entries(byLocale)) {
930
- log(`${loc}: ${info.missing} missing (${info.coverage}% coverage)`)
934
+ log(`${loc}: ${info.missing} missing${info.outdated ? `, ${info.outdated} outdated` : ''} (${info.coverage}% coverage)`)
935
+ }
936
+
937
+ // The old translation still shows. Replace the entry with a string once it is reviewed.
938
+ if (allOutdated.length > 0) {
939
+ log(`\n${colors.bright}Outdated${colors.reset} ${colors.dim}(its source has changed; the old translation still shows)${colors.reset}`)
940
+ for (const entry of allOutdated) {
941
+ log(` ${entry.locale} ${entry.source}`)
942
+ log(` ${colors.dim} was: ${entry.was.join(' | ')}${colors.reset}`)
943
+ log(` ${colors.dim} now: ${entry.translation}${colors.reset}`)
944
+ }
931
945
  }
932
946
 
933
947
  if (allMissing.length === 0) {
934
- log(`\n${colors.green}All strings are translated!${colors.reset}`)
948
+ if (allOutdated.length === 0) log(`\n${colors.green}All strings are translated!${colors.reset}`)
935
949
  return
936
950
  }
937
951
 
@@ -103,12 +103,14 @@ import {
103
103
  deploymentFields,
104
104
  ensureRegisteredFoundation,
105
105
  recoverUnbankedIdentity,
106
+ keepTranslationsOfEdits,
106
107
  ensureSiteExists,
107
108
  refuseUnsendableRecords,
108
109
  clearRemoteSyncStateIfUnbound,
109
110
  untakenBase,
110
111
  unsettledFiles,
111
112
  commitWriteBacks,
113
+ deployRecordAtRest,
112
114
  reportWriteBacks,
113
115
  pushSyncPackages,
114
116
  readSiteWorkspace
@@ -126,6 +128,7 @@ import {
126
128
  } from '@uniweb/build/uwx'
127
129
  import {
128
130
  bringFoundationAlong,
131
+ filesAReleaseWrites,
129
132
  bringExtensionsAlong
130
133
  } from '../backend/foundation-bring-along.js'
131
134
  import {
@@ -516,6 +519,9 @@ export async function publish(args = []) {
516
519
  return { exitCode: 0 }
517
520
  }
518
521
 
522
+ // What the release may write into local code, for the push to commit with what it writes.
523
+ const released = await filesAReleaseWrites(siteDir, siteYml)
524
+
519
525
  // 1. Bring the foundation along — release the local foundation if its code
520
526
  // changed (or isn't registered). Never ship a site pointing at stale code.
521
527
  let fnd
@@ -959,6 +965,9 @@ export async function publish(args = []) {
959
965
  // Identity the backend holds and this copy lacks — see `uniweb push`.
960
966
  const again = await recoverUnbankedIdentity({ client, siteDir, pkg, note: (m) => say.dim(m) })
961
967
  if (again) pkg = await emitSyncPackages(siteDir, { ...emitOptions, ...again })
968
+ if (await keepTranslationsOfEdits({ client, siteDir, pkg, note: (m) => say.dim(m) })) {
969
+ pkg = await emitSyncPackages(siteDir, { ...emitOptions, ...again })
970
+ }
962
971
  } catch (err) {
963
972
  say.err(`Could not build the sync package: ${err.message}`)
964
973
  return { exitCode: 1 }
@@ -986,7 +995,7 @@ export async function publish(args = []) {
986
995
  report
987
996
  })
988
997
  // What the push wrote into the files is committed, whatever became of the lanes.
989
- reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: pushResult.complete }), { note: say.dim })
998
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: pushResult.complete, released }), { note: say.dim })
990
999
  if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
991
1000
  const siteUuid = pushResult.boundSiteUuid
992
1001
  if (!siteUuid) {
@@ -1077,6 +1086,7 @@ export async function publish(args = []) {
1077
1086
  ? siteYml.foundation
1078
1087
  : siteYml.foundation?.ref || null
1079
1088
  const recordedRef = fnd.ref || siteYmlRef
1089
+ const recordAtRest = deployRecordAtRest(siteDir)
1080
1090
  await persistLastDeploy(siteDir, {
1081
1091
  targetName: resolved.targetName,
1082
1092
  // A target this file does not have yet — the first publish anywhere (the whole
@@ -1118,6 +1128,12 @@ export async function publish(args = []) {
1118
1128
  ...(Array.isArray(result.locales) ? { locales: result.locales } : {})
1119
1129
  }
1120
1130
  })
1131
+ // ⭐ The record is committed, as what a push writes is. ⛔ Until 2026-10-30 every publish left
1132
+ // `deploy.yml` changed, so a tree a person had committed was never clean after one.
1133
+ if (recordAtRest && saveDeploys) {
1134
+ const recorded = commitWriteBacks(siteDir, client.origin, { only: ['deploy.yml'] })
1135
+ if (recorded?.error) reportWriteBacks(recorded, { note: say.dim })
1136
+ }
1121
1137
 
1122
1138
  console.log('')
1123
1139
  say.ok(
@@ -104,6 +104,8 @@ import {
104
104
  writeItemBaseVersions,
105
105
  pulledItemVersions,
106
106
  writeUnitBases,
107
+ commitWriteBacks,
108
+ reportWriteBacks,
107
109
  writeItemUuids,
108
110
  writeFolderItemUuids
109
111
  } from '../backend/site-sync.js'
@@ -241,7 +243,10 @@ function pullCachePath(siteDir) {
241
243
  // content it never took. Every later pull then answered 304 and the file never caught up.
242
244
  // Ignoring those once costs one full pull. (In a repository an ETag is echoed only while
243
245
  // the sync point it was banked with is in the history — see `cacheHolds` below.)
244
- const PULL_CACHE_VERSION = 2
246
+ // ⛔ VERSION 3 DISOWNS THOSE OF A PULL THAT READ NOTHING OF `@`. Before 2026-10-31 a pull took a
247
+ // translation the app had flagged for current, and kept nothing of `@`. A site that has not moved
248
+ // since would answer 304, and its next push would remove what the app keeps there.
249
+ const PULL_CACHE_VERSION = 3
245
250
  export function readPullCache(siteDir) {
246
251
  try {
247
252
  const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
@@ -1115,15 +1120,17 @@ export async function pull(args = [], deps = {}) {
1115
1120
  let pulledRecordDocs = []
1116
1121
  let merge = { conflicted: [], changed: [] }
1117
1122
  let notTaken = false
1123
+ // The languages the backend holds text in that the site does not list: not written (`documentLanguages`).
1124
+ let outsideLanguages = []
1118
1125
  try {
1119
1126
  if (siteDoc) {
1120
1127
  // Re-base the page attribution. The pulled document IS the backend's own
1121
- // representation, so it becomes the remote base directly. We deliberately
1122
- // CLEAR the local base rather than reuse it: our source files were just
1123
- // rewritten from this document, and what we would emit from them is not
1124
- // byte-identical to it, so the old local base no longer describes anything.
1125
- // The next push re-establishes it; until then our side reports as unknown,
1126
- // which is honest rather than wrong.
1128
+ // representation, so it becomes the remote base directly. We CLEAR the local
1129
+ // base rather than reuse it: our source files were just rewritten from this
1130
+ // document, and what we would emit from them is not byte-identical to it, so
1131
+ // the old local base no longer describes anything. The re-bank below sets it
1132
+ // from what we would emit; if that fails our side reports as unknown, which is
1133
+ // honest rather than wrong.
1127
1134
  writeUnitBases(projDir, client.origin, { remote: computeUnitHashes(siteDoc), local: {} })
1128
1135
  pulledVersions = pulledItemVersions(siteDoc, content.itemVersions)
1129
1136
  // Per-item identity for the next push. Without it the backend reads our
@@ -1181,6 +1188,7 @@ export async function pull(args = [], deps = {}) {
1181
1188
  sections += report.sections.length
1182
1189
  deleted += report.deleted.length
1183
1190
  leftAlone += report.leftAlone?.length || 0
1191
+ outsideLanguages = report.outsideLanguages || []
1184
1192
  }
1185
1193
 
1186
1194
  if (folderTaken) {
@@ -1309,7 +1317,8 @@ export async function pull(args = [], deps = {}) {
1309
1317
  await rebankSyncHashes(projDir, client.origin, {
1310
1318
  recordDocs: pulledRecordDocs,
1311
1319
  ...(declarations.size ? { declarations } : {}),
1312
- fields
1320
+ fields,
1321
+ contentTaken: Boolean(siteDoc)
1313
1322
  })
1314
1323
  } catch (err) {
1315
1324
  note(`! could not re-bank the sync cache: ${err.message}`)
@@ -1402,6 +1411,12 @@ export async function pull(args = [], deps = {}) {
1402
1411
  }
1403
1412
  standIn.close()
1404
1413
  standIn = null
1414
+ // ⭐ And the identity it wrote, `sync.json`, as a push commits it: one new section in the app
1415
+ // changes it. ⛔ Until 2026-10-30 a pull that brought one left the file changed, until the next push.
1416
+ if (!notTaken && !merge.conflicted.length) {
1417
+ const recorded = commitWriteBacks(siteDir, client.origin, { only: ['sync.json'] })
1418
+ if (recorded?.error) reportWriteBacks(recorded, { note })
1419
+ }
1405
1420
  }
1406
1421
  } finally {
1407
1422
  standIn?.close()
@@ -1450,6 +1465,16 @@ export async function pull(args = [], deps = {}) {
1450
1465
  'An edit made to one in the app does not come back here, and the next push sends the file.'
1451
1466
  )
1452
1467
  }
1468
+ // ⭐ Said, because the text is not in a translation file: one would make the language the site's,
1469
+ // and the next publish would ask to serve it (`uwx/source-locale.js`). It is kept for the push to
1470
+ // send back (`locales/_kept.json`), since a language removed in the app keeps its translations.
1471
+ if (outsideLanguages.length) {
1472
+ info(
1473
+ `The app holds text in ${outsideLanguages.join(', ')}, which this site does not list among its languages, ` +
1474
+ 'so it is not published. It is kept, and your translation files leave it out.'
1475
+ )
1476
+ note('To use it, add the language in the app (Site ▸ Languages), then pull again.')
1477
+ }
1453
1478
  if (repo && !notTaken) {
1454
1479
  // ⭐ What the pull changed in the files — not the backend's content against the base,
1455
1480
  // which also lists what the files already held (`changedInFiles`).
@@ -80,7 +80,7 @@ import {
80
80
  import { confirm, isNonInteractive } from '../utils/interactive.js'
81
81
  import { announceServices, foundationSupports } from '../backend/service-request.js'
82
82
  import { guardEmptyRecords, noteFolderLeftAlone } from '../utils/records-guard.js'
83
- import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
83
+ import { bringFoundationAlong, filesAReleaseWrites } from '../backend/foundation-bring-along.js'
84
84
  import { repoOf } from '../utils/sync-point.js'
85
85
  import {
86
86
  makeModelResolver,
@@ -99,6 +99,7 @@ import {
99
99
  ensureSiteExists,
100
100
  clearRemoteSyncStateIfUnbound,
101
101
  untakenBase,
102
+ keepTranslationsOfEdits,
102
103
  unsettledFiles,
103
104
  commitWriteBacks,
104
105
  reportWriteBacks,
@@ -298,6 +299,8 @@ export async function push(args = [], deps = {}) {
298
299
  err: error,
299
300
  dim: note
300
301
  }
302
+ // What the release may write into local code, for the push to commit with what it writes.
303
+ const released = output || dryRun ? [] : await filesAReleaseWrites(siteDir, siteYml)
301
304
  let fnd = { ref: null }
302
305
  try {
303
306
  fnd = await bringFoundationAlong({
@@ -620,6 +623,9 @@ export async function push(args = [], deps = {}) {
620
623
  const again =
621
624
  output || dryRun ? null : await recoverUnbankedIdentity({ client, siteDir, pkg, note })
622
625
  if (again) pkg = await emitSyncPackages(siteDir, { ...emitOptions, ...again })
626
+ if (!output && !dryRun && (await keepTranslationsOfEdits({ client, siteDir, pkg, note }))) {
627
+ pkg = await emitSyncPackages(siteDir, { ...emitOptions, ...again })
628
+ }
623
629
  } catch (err) {
624
630
  error(`Could not build the sync package: ${err.message}`)
625
631
  return { exitCode: 2 }
@@ -649,7 +655,7 @@ export async function push(args = [], deps = {}) {
649
655
  if (!output && !dryRun) {
650
656
  holdUnchangedPush(siteDir, client.origin)
651
657
  // What it recorded on the way — a media map, an identity recovered — is committed too.
652
- reportWriteBacks(commitWriteBacks(siteDir, client.origin), { note })
658
+ reportWriteBacks(commitWriteBacks(siteDir, client.origin, { released }), { note })
653
659
  }
654
660
  return { exitCode: 0 }
655
661
  }
@@ -712,7 +718,7 @@ export async function push(args = [], deps = {}) {
712
718
  }
713
719
  })
714
720
  // What the push wrote into the files is committed, whatever became of the lanes.
715
- const written = commitWriteBacks(siteDir, client.origin, { complete: result.complete })
721
+ const written = commitWriteBacks(siteDir, client.origin, { complete: result.complete, released })
716
722
  if (result.exitCode !== 0) {
717
723
  reportWriteBacks(written, { note })
718
724
  return { exitCode: result.exitCode }
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-10-31T02:20:56.213Z",
3
+ "generatedAt": "2026-10-31T13:54:14.240Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.7"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.13.2"
9
+ "version": "1.13.4"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.7"
@@ -54,7 +54,7 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.1.9"
57
+ "version": "1.1.10"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
package/src/index.js CHANGED
@@ -1986,6 +1986,139 @@ ${colors.bright}Or skip the login.${colors.reset} With \`UNIWEB_TOKEN\` set —
1986
1986
  session, and nothing is stored. \`uniweb login\` there only checks the token with the
1987
1987
  backend those commands go to — \`UNIWEB_SERVER\`, else the one you are logged in to,
1988
1988
  else the default — and says who and where they work as.
1989
+ `,
1990
+ push: `
1991
+ ${colors.cyan}${colors.bright}uniweb push${colors.reset} ${colors.dim}— Send this site's content to the app${colors.reset}
1992
+
1993
+ ${colors.bright}Usage:${colors.reset}
1994
+ uniweb push [options]
1995
+
1996
+ Sends the site's content to the backend you are logged in to, releasing the local
1997
+ foundation first if its code changed. The site is not live until \`uniweb publish\`.
1998
+
1999
+ In a git repository a push sends what is committed. It is refused, with nothing
2000
+ written, if the site changed in the app since your last pull: run \`uniweb pull\` to
2001
+ merge those changes with yours, then push again.
2002
+
2003
+ ${colors.bright}Options:${colors.reset}
2004
+ --commit In a git repository, commit the site's content first (-m <message>)
2005
+ --dry-run Report what would be sent; send nothing
2006
+ -o <file> Write what would be sent to a file; send nothing
2007
+ --all Send everything, not only what changed
2008
+ --force Overwrite what changed in the app since your last pull
2009
+ --no-release Send content against the code already released; release nothing
2010
+ --bump Release above a newer registered foundation version
2011
+ --foundation <dir> Use this local foundation
2012
+ --no-validate Skip the content-conformance check, which stops a push
2013
+ --yes Skip confirmations; never block on a prompt
2014
+ --org @org Work in @org for this push, instead of the workspace chosen at
2015
+ --personal \`uniweb login\` (or your personal workspace)
2016
+ `,
2017
+ pull: `
2018
+ ${colors.cyan}${colors.bright}uniweb pull${colors.reset} ${colors.dim}— Bring the site's content from the app into your files${colors.reset}
2019
+
2020
+ ${colors.bright}Usage:${colors.reset}
2021
+ uniweb pull [options]
2022
+
2023
+ In a git repository, merges what changed in the app with your commits, and commits
2024
+ the app's side so the next pull can tell the two apart. A section both sides changed
2025
+ is left with conflict markers to settle, then \`git add\` and \`git commit\`.
2026
+
2027
+ Outside a repository there is nothing to merge against: the files are rewritten to
2028
+ what the backend holds, after asking if any of them are yours.
2029
+
2030
+ ${colors.bright}Options:${colors.reset}
2031
+ --dry-run Report what it would fetch; write nothing
2032
+ --force Take the backend's version, discarding local changes
2033
+ --no-records Pull pages only; skip records
2034
+ --no-assets Don't download media; the content keeps its URLs
2035
+ --no-delete Outside a repository, keep files with no backend item
2036
+ --org @org Work in @org for this pull, instead of the workspace chosen at
2037
+ --personal \`uniweb login\` (or your personal workspace)
2038
+
2039
+ To catch up with your git remote as well, use \`uniweb refresh\`.
2040
+ `,
2041
+ clone: `
2042
+ ${colors.cyan}${colors.bright}uniweb clone${colors.reset} ${colors.dim}— Copy a site from the app into a new local project${colors.reset}
2043
+
2044
+ ${colors.bright}Usage:${colors.reset}
2045
+ uniweb clone <site-uuid> [name|.] [options]
2046
+
2047
+ Makes a project from a site you can reach on the backend you are logged in to, with
2048
+ the site's foundation as a pinned reference. It starts a git repository, so the first
2049
+ pull and push have something to merge against. Find the uuid with \`uniweb site list\`.
2050
+
2051
+ With \`.\`, clones into the current folder. Inside a workspace, adds the site to it.
2052
+
2053
+ ${colors.bright}Options:${colors.reset}
2054
+ --path <dir> Place the site under this folder (for example, sites)
2055
+ --project <name> Place it as a co-located <name>/site
2056
+ --no-records Pull pages only; skip records
2057
+ --no-assets Don't download media; the content keeps its URLs
2058
+ --no-git Don't start a git repository
2059
+ --org @org Work in @org for this clone, instead of the workspace chosen at
2060
+ --personal \`uniweb login\` (or your personal workspace)
2061
+ `,
2062
+ site: `
2063
+ ${colors.cyan}${colors.bright}uniweb site${colors.reset} ${colors.dim}— The sites in a workspace${colors.reset}
2064
+
2065
+ ${colors.bright}Usage:${colors.reset}
2066
+ uniweb site list [--json]
2067
+ uniweb site unpublish [<site-uuid>] [--yes]
2068
+ uniweb site delete [<site-uuid>] [--yes]
2069
+
2070
+ ${colors.bright}list${colors.reset} gives each site's name, uuid, and whether it is live.
2071
+ ${colors.bright}unpublish${colors.reset} takes a site offline, and its content stays.
2072
+ ${colors.bright}delete${colors.reset} removes a site for good. A live site must be unpublished first.
2073
+
2074
+ Without a uuid, \`unpublish\` and \`delete\` act on the site this project is synced to.
2075
+ Both ask first, and \`--yes\` is the only way past the question: with no terminal and
2076
+ no \`--yes\` they refuse. Deleting this project's own site also forgets it here, so the
2077
+ next push creates a new one.
2078
+
2079
+ ${colors.bright}Options:${colors.reset}
2080
+ --json \`list\`: print JSON
2081
+ --yes Confirm \`unpublish\` or \`delete\`
2082
+ --org @org Work in @org, instead of the workspace chosen at \`uniweb login\`
2083
+ --personal (or your personal workspace)
2084
+ `,
2085
+ org: `
2086
+ ${colors.cyan}${colors.bright}uniweb org${colors.reset} ${colors.dim}— The organizations you belong to${colors.reset}
2087
+
2088
+ ${colors.bright}Usage:${colors.reset}
2089
+ uniweb org list
2090
+ uniweb org create <handle>
2091
+
2092
+ ${colors.bright}list${colors.reset} gives your personal scope and the organizations you are a member of.
2093
+ ${colors.bright}create${colors.reset} makes an organization, with you as a member.
2094
+
2095
+ You don't need one to register a foundation: \`@<your handle>\` is your personal scope.
2096
+ An organization is for a scope, and sites, that you share.
2097
+ `,
2098
+ content: `
2099
+ ${colors.cyan}${colors.bright}uniweb content${colors.reset} ${colors.dim}— Package a site or foundation as a file${colors.reset}
2100
+
2101
+ ${colors.bright}Usage:${colors.reset}
2102
+ uniweb content export [<dir>] [options]
2103
+
2104
+ Writes the content of a site (a folder with \`site.yml\`), or the schema of a built
2105
+ foundation, to one file, with no code in it. To send a site to the app, use
2106
+ \`uniweb push\`.
2107
+
2108
+ ${colors.bright}Options:${colors.reset}
2109
+ -o <file> Choose the output filename
2110
+ --dry-run Print a summary; write nothing
2111
+ --no-sidecar Mint fresh ids each time, for a file submitted once
2112
+ --source-locale <lang> Wrap single-language fields under this language (default: en)
2113
+ `,
2114
+ logout: `
2115
+ ${colors.cyan}${colors.bright}uniweb logout${colors.reset} ${colors.dim}— Log out of the backend you are logged in to${colors.reset}
2116
+
2117
+ ${colors.bright}Usage:${colors.reset}
2118
+ uniweb logout
2119
+
2120
+ Forgets the session on this computer. The next command that needs a backend asks you to
2121
+ log in again, and \`uniweb login\` goes to the default backend unless you name another.
1989
2122
  `,
1990
2123
  refresh: `
1991
2124
  ${colors.cyan}${colors.bright}uniweb refresh${colors.reset} ${colors.dim}— Catch up with teammates AND app authors${colors.reset}
@@ -2220,6 +2353,7 @@ ${colors.bright}Commands:${colors.reset}
2220
2353
  status What changed in the app, in git and in Uniweb — and what to run
2221
2354
  forget Forget a backend, or --all to make a copied project a new one
2222
2355
  site <cmd> The sites in a workspace: list, unpublish, delete
2356
+ org <cmd> The organizations you belong to: list, create
2223
2357
  inspect <path> Inspect parsed content shape of a markdown file or folder
2224
2358
  docs Generate component documentation
2225
2359
  families List the standard section families (for meta.js family:)
@@ -49,7 +49,7 @@ import {
49
49
  writeFileSync
50
50
  } from 'node:fs'
51
51
  import { tmpdir } from 'node:os'
52
- import { join, dirname } from 'node:path'
52
+ import { join, dirname, posix } from 'node:path'
53
53
 
54
54
  export const SYNC_TRAILER = 'Uniweb-Sync'
55
55
  export const SITE_TRAILER = 'Uniweb-Site'
@@ -747,7 +747,7 @@ export function contentCommitted(repo, roots) {
747
747
  export function uncommittedPaths(repo, roots) {
748
748
  let parts
749
749
  try {
750
- parts = zlist(git(repo.top, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...roots.map((r) => `${repo.prefix}${r}`)]))
750
+ parts = zlist(git(repo.top, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...roots.map((r) => underTop(repo, r))]))
751
751
  } catch {
752
752
  return null
753
753
  }
@@ -794,7 +794,7 @@ export function filesDifferFrom(repo, rev, roots) {
794
794
  * @returns {{ commit: string, paths: string[] } | null} null when there was nothing to commit
795
795
  */
796
796
  export function commitRoots(repo, roots, { message, identity = null }) {
797
- const full = roots.map((r) => `${repo.prefix}${r}`)
797
+ const full = roots.map((r) => underTop(repo, r))
798
798
  const present = full.filter((p) => existsSync(join(repo.top, p)) || zlist(git(repo.top, ['ls-files', '-z', '--', p])).length)
799
799
  let addable = present
800
800
  if (present.length) {
@@ -818,6 +818,9 @@ export function commitRoots(repo, roots, { message, identity = null }) {
818
818
 
819
819
  const siteRelative = (repo, p) => (repo.prefix && p.startsWith(repo.prefix) ? p.slice(repo.prefix.length) : p)
820
820
 
821
+ // A path relative to the site, as the repository names it. `../src/main.js` comes out as `src/main.js`.
822
+ const underTop = (repo, p) => posix.normalize(`${repo.prefix}${p}`)
823
+
821
824
  // ── this copy's own sync point ──────────────────────────────────────────────
822
825
 
823
826
  const cachePath = (siteDir) => join(siteDir, '.uniweb', 'backend-cache.json')