uniweb 1.26.3 → 1.26.5

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.26.3",
3
+ "version": "1.26.5",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,12 +42,12 @@
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/content-writer": "~1.3.1",
45
- "@uniweb/core": "~1.6.3",
46
- "@uniweb/semantic-parser": "~1.13.2",
47
- "@uniweb/schemas": "~1.6.7"
45
+ "@uniweb/core": "~1.6.4",
46
+ "@uniweb/schemas": "~1.6.7",
47
+ "@uniweb/semantic-parser": "~1.13.2"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.15.2",
50
+ "@uniweb/build": "~1.15.3",
51
51
  "@uniweb/content-reader": "~1.5.8",
52
52
  "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
@@ -100,6 +100,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
100
100
  | `<a href="/about">` | `<Link to="page:about">` (an `id:` survives moves) or `<Link href="/about">`. A bare `<a>` still routes but resolves no `page:` and adds no base path or locale. | silent |
101
101
  | `window.location.href = '/fr'` to switch language | `<Link reload href={website.getLocaleUrl('fr')}>` or `website.switchLocale('fr')`. | base-path bug |
102
102
  | `useEffect(() => fetch(…))` for records | Declare the key in `meta.js data:`; it arrives in `content.data`, prerendered. | prerenders as loading |
103
+ | `<Icon icon="lu-send" />` for an icon your section always shows | Import it (`uniweb guide foundation` § Icon). A name is for an icon content supplies at runtime: markdown, a param, a record's field. | silent; blank until the browser fetches it |
103
104
  | A `Button` or `Card` in `sections/` | `components/`. Everything at the root of `sections/` becomes author vocabulary. | appears in the section picker |
104
105
  | Helpers that take `{ content, params }` | Ordinary props. That signature is for section types only. | — |
105
106
  | One section type per visual variant; or one with a conditional tree inside | A front desk (§1): one `type:`, a `variant` param, workers in `components/` with ordinary props. | author vocabulary bloats; variants invisible to the editor |
@@ -53,7 +53,7 @@ The body — `body.content`.
53
53
 
54
54
  Paths are relative to `records/`, one file or a glob. An entry can be `{ path, tags, label }` — delivered beside the record as `$tags` (in order) and `$label` (one text or `{ en, fr }`, resolved to the page's language); a query reads them like any key (`where: { $tags: featured }`). `scope: archive` reads the folder and everything inside. A record sits in one folder; a computed subset is a query. The build refuses a top-level bare path (every file is a record already).
55
55
 
56
- **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` removes them (the CLI asks). Records with a data schema reach published pages only when `services.records: true`.
56
+ **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its folder, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
57
57
 
58
58
  ## Queries
59
59
 
@@ -78,14 +78,22 @@ Things you won't discover from exports:
78
78
 
79
79
  ### Icon
80
80
 
81
+ **An icon your code draws is imported**, so it is in the page from the first render, with nothing to fetch:
82
+
83
+ ```jsx
84
+ import send from '@uniweb/icons/families/lu/send.js' // a dependency: npm install @uniweb/icons
85
+ <Icon svg={send} size="18" />
86
+ ```
87
+
88
+ `@uniweb/icons` holds Lucide (`lu`), Heroicons (`hi`, `hi2`) and Feather (`fi`), the same drawings an author's names get, named as the corpus spells them (`building2.js`). For another family, import its SVG as a string, or its component, from that family's own package. **An icon an author names arrives as a name**, and `<Icon>` fetches it, since a site has no build:
89
+
81
90
  ```jsx
82
- {content.icons.map((icon, i) => <Icon key={i} {...icon} />)}
83
- <Icon name="search" /> // Lucide default
84
- <Icon name="hi2-arrow-right" /> // other library by prefix
85
- <Icon name="close" /> // built-in, no network: check close menu chevronDown chevronRight externalLink download play …
91
+ {content.icons.map((icon, i) => <Icon key={i} {...icon} />)} // the section's markdown
92
+ <Icon icon={record.icon} /> // a record's field or a param: `lu-baby`
93
+ <Icon name="close" /> // built-in, no network: check close menu chevronDown chevronRight externalLink download play …
86
94
  ```
87
95
 
88
- Other props: `svg`, `url`, `size` (default `'24'`), `className`.
96
+ A name written in your code (`<Icon name="search" />`) is fetched the same way: until the browser has it, a prerendered page can show an empty box in its place. Other props: `url`, `size` (default `'24'`), `className`.
89
97
 
90
98
  ## Section wrapper and sticky
91
99
 
@@ -28,7 +28,7 @@ services:
28
28
  google: { id: G-XXXXXXXXXX } # Uniweb Cloud loads Google's tag; a static build ignores it (Tracking)
29
29
  ```
30
30
 
31
- An entry is `true`, `false`, an address (a string, or `endpoint:` in a map), or a map of options (`records` and `google` take no address); anything else stops the build and the push. `yes`/`no`/`on`/`off` are text in YAML — write `true`/`false`. On a site you push or publish it is also what you ask the host for: `true` asks for its service, `false` turns it off, an address asks the host to leave its own off so yours answers. **A hosted site's services are off unless `services:` asks** — list the ones the site uses. Turn `records: true` on before publishing a page that shows schema records (a static build ignores it; `publish` warns). An entry says everything about its service: removing a setting removes it on the next push; removing the entry switches it off. `push`/`publish` send each service listed; one turned on in the app since your last pull is left alone; one changed on both sides stops the push — `uniweb pull`, then push. `uniweb pull` writes what the site has into `services:`. A change that needs payment is settled in the app (`publish` opens it). Everything in an entry is public except `backend`'s settings; a key or token is set in the app.
31
+ An entry is `true`, `false`, an address (a string, or `endpoint:` in a map), or a map of options (`records` and `google` take no address); anything else stops the build and the push. `yes`/`no`/`on`/`off` are text in YAML — write `true`/`false`. On a site you push or publish it is also what you ask the host for: `true` asks for its service, `false` turns it off, an address asks the host to leave its own off so yours answers. **A hosted site's services are off unless `services:` asks** — list the ones the site uses. Turn `records: true` on before publishing a page that shows schema records (a static build ignores it; `publish` warns). An entry says everything about its service: removing a setting removes it on the next push; removing the entry switches it off. `push`/`publish` send each service listed; one turned on in the app since your last pull is left alone; one changed on both sides stops the push — `uniweb pull`, then push. `uniweb pull` writes what the site has into `services:`. A change that needs payment is settled in the app (`publish` opens it). Everything in an entry is public except `backend`'s settings. A key or token never goes in a file: `uniweb site secret <service> <name>` asks for it at a terminal, and the live site has it from its next publish.
32
32
 
33
33
  ### Declaring what your foundation supports
34
34
 
@@ -121,6 +121,16 @@ The endpoint must accept the framework's batched `{ "events": [ … ] }` POST (`
121
121
 
122
122
  Someone who edits only in the app adds it there, with no terminal: the *Google Analytics and Tag Manager* card in the site's Settings, under Features, then a publish. It is this same entry: `uniweb pull` writes what the card holds into `site.yml`, its switch as `enabled: false`. Leave `services.tracking.scripts` unset beside it — a site's own list replaces what the host states, so Google's tag would not load. `tracking: { enabled: false, consent: required }` beside it holds the tag until a visitor answers, and needs a component using `useTrackingConsent()`, or it never loads. Gate that component on the hook's `status`: `isTrackingEnabled()` is false here. Any other such vendor has to run from the foundation's code, so a site whose foundation you can't change can't add one — say so rather than writing a `head.html` that does nothing.
123
123
 
124
+ **X and Meta, on Uniweb Cloud, need nothing in a page:** the host sends the site's conversions to the platform from its servers, for a visitor who arrived from one of its ads (`twclid`, `fbclid`). Name the pixel, in quotes, and map each conversion name to the event made for it on the platform:
125
+
126
+ ```yaml
127
+ services:
128
+ x: { pixel: 'o1abc', events: { signup: 'tw-o1abc-o2def' } }
129
+ meta: { pixel: '1234567890123456', events: { signup: CompleteRegistration } }
130
+ ```
131
+
132
+ Then the person sets each token with `uniweb site secret x token` (or `meta token`) and publishes. The command asks for the token at a prompt and refuses with no terminal, so an agent never handles it: tell the person to run it. A name with no `events` entry, and any engagement, is never sent; a landing address with `utm_campaign=test` marks a test click, never sent. A site's own `tracking.landing` replaces the host's, so keep `twclid` and `fbclid` in it. A static build leaves these rows out.
133
+
124
134
  Either way, tell the person to check Realtime from a browser that doesn't block trackers: a visit from Brave, say, never reaches Google, which looks like a failed install. Google Analytics counts each page a visitor moves to through the browser-history setting, under Enhanced measurement in the data stream's settings, which a new stream has on.
125
135
 
126
136
  A Tag Manager container needs nothing more, so don't present what follows as limits; use it if it comes up. A tag that doesn't follow page changes on its own, unlike Google Analytics or Meta's pixel, uses Tag Manager's *History Change* trigger, as on any site that changes pages without reloading. Tag Assistant shows the tags that fired, and Google doesn't report a mistyped ID as an error. If a container already sends to a Measurement ID, list only the container, so pages aren't counted twice. Foundation code sends a container its own events with `(window.dataLayer = window.dataLayer || []).push({ event: 'name' })`; `track()` doesn't reach Google.
@@ -0,0 +1,12 @@
1
+ /**
2
+ * The ad platforms a site can name in `site.yml::services`: `services.x`, `services.meta`.
3
+ *
4
+ * Each is a row the host acts on: it sends the site's conversions on to that platform, server
5
+ * side, with the site's own token. So a foundation renders nothing for one, `uniweb status` never
6
+ * hears one reported as live, and a platform's token is a secret for the host to read.
7
+ *
8
+ * ⭐ ONE LIST FOR THE CLI. `@uniweb/build` checks the rows as they are written and keeps its own
9
+ * (`AD_PLATFORMS` in `uwx/services-request.js`), since the CLI may run where that package is not
10
+ * installed. A new platform is a name added here and there.
11
+ */
12
+ export const AD_PLATFORMS = new Set(['meta', 'x'])
@@ -115,8 +115,8 @@ export const DISCOVERY_DEFAULTS = {}
115
115
  *
116
116
  * ⭐ `@<handle>`, the `@` required: a bare value is read as a unit's uuid — the spelling
117
117
  * for a workspace with no handle — so the two can never be mistaken for each other.
118
- * Every `/dev` route accepts it; the client names it on the site routes, the ones that
119
- * work in a workspace (`namesWorkspace`). ⛔ It replaced `?as_org=` (2026-09-23), which
118
+ * Every `/dev` route accepts it; the client names it on the routes that work in a workspace,
119
+ * the site routes and `/dev/entities` (`namesWorkspace`). ⛔ It replaced `?as_org=` (2026-09-23), which
120
120
  * only routes that declared it accepted — the rest answered `400`.
121
121
  */
122
122
  export const WORKSPACE_HEADER = 'x-uniweb-workspace'
@@ -134,7 +134,8 @@ export const SOURCE_HEADER = 'x-uniweb-source'
134
134
  const sourceHeaders = (source) => (source ? { [SOURCE_HEADER]: source } : {})
135
135
 
136
136
  /**
137
- * Whether a request works IN a workspace — a site route, `/dev/site…`.
137
+ * Whether a request works IN a workspace — a site route, `/dev/site…`, or `/dev/entities…`,
138
+ * which acts on entities of the workspace it names (an entity outside it is refused, `409`).
138
139
  *
139
140
  * Only those name one. Every `/dev` route accepts the header, but registration reads
140
141
  * none (the `@scope` in the name decides, membership-gated), `/dev/assets` reads none
@@ -147,7 +148,7 @@ const sourceHeaders = (source) => (source ? { [SOURCE_HEADER]: source } : {})
147
148
  * @returns {boolean}
148
149
  */
149
150
  export function namesWorkspace(path) {
150
- return /^\/dev\/site(\/|$)/.test(String(path))
151
+ return /^\/dev\/(site|entities)(\/|$)/.test(String(path))
151
152
  }
152
153
 
153
154
  /**
@@ -959,6 +960,53 @@ export class BackendClient {
959
960
  return this.request(`/dev/site/${encodeURIComponent(uuid)}`, { method: 'DELETE' })
960
961
  }
961
962
 
963
+ /**
964
+ * POST /dev/entities/delete — delete entities by uuid, in the workspace the client names:
965
+ * `{ uuids, placed?: 'keep' | 'delete', rev_ref_policy?: 'abort' | 'orphan_refs' }`. Answers
966
+ * `{ deleted, kept }`: with `placed: 'keep'`, the default, an entity a folder outside the call
967
+ * still places is kept and named in `kept`. A uuid that names no entity is in neither list. One
968
+ * entity the caller may not administer refuses the whole call (`403`), and nothing is deleted.
969
+ *
970
+ * @param {{ uuids: string[], placed?: string, rev_ref_policy?: string }} body
971
+ * @returns {Promise<Response>}
972
+ */
973
+ async deleteEntities(body) {
974
+ return this.request('/dev/entities/delete', { method: 'POST', body: JSON.stringify(body) })
975
+ }
976
+
977
+ /**
978
+ * PUT /dev/site/secrets/{uuid} — set one of a site's secrets, keyed by `(service, name)`:
979
+ * `{ service?, name, consumer?, value }`. Answers `{ service, name, consumer, set: true, mask }`,
980
+ * never the value. Only an admin of the site may (`403` for an editor). A value set here
981
+ * reaches the live site at its next publish. Refused `400 invalid_field` naming the body key.
982
+ *
983
+ * @param {string} uuid - the site-content uuid
984
+ * @param {{ service?: string, name: string, consumer?: string, value: string }} body
985
+ * @returns {Promise<Response>}
986
+ */
987
+ async setSiteSecret(uuid, body) {
988
+ return this.request(`/dev/site/secrets/${encodeURIComponent(uuid)}`, {
989
+ method: 'PUT',
990
+ body: JSON.stringify(body)
991
+ })
992
+ }
993
+
994
+ /**
995
+ * DELETE /dev/site/secrets/{uuid} — clear one of a site's secrets: `{ service?, name }`.
996
+ * Answers `{ service, name, consumer, set: false }`. The live site keeps the old value until
997
+ * its next publish.
998
+ *
999
+ * @param {string} uuid - the site-content uuid
1000
+ * @param {{ service?: string, name: string }} body
1001
+ * @returns {Promise<Response>}
1002
+ */
1003
+ async clearSiteSecret(uuid, body) {
1004
+ return this.request(`/dev/site/secrets/${encodeURIComponent(uuid)}`, {
1005
+ method: 'DELETE',
1006
+ body: JSON.stringify(body)
1007
+ })
1008
+ }
1009
+
962
1010
  /**
963
1011
  * GET /dev/site/status/{uuid} → the site's publish lifecycle (Contract 3,
964
1012
  * shipped backend-side — collab backend↔framework):
@@ -28,6 +28,7 @@ import { createHash } from 'node:crypto'
28
28
  import { existsSync, readFileSync } from 'node:fs'
29
29
  import { join } from 'node:path'
30
30
  import { readServicesRequest, unreadableServices } from '@uniweb/build/uwx'
31
+ import { AD_PLATFORMS } from './ad-platforms.js'
31
32
 
32
33
  /**
33
34
  * A stable fingerprint of one declared value, or `null` when the key is absent.
@@ -194,9 +195,9 @@ export function serviceNotes({ siteYml, supports = null, warn = () => {} }) {
194
195
  }
195
196
  if (!Array.isArray(supports)) return notes
196
197
  // None of these is something a foundation renders: `google` and `tracking` load or report
197
- // whatever the foundation is, `meta` and `x` hear its conversions from the host, and `records`
198
+ // whatever the foundation is, an ad platform hears its conversions from the host, and `records`
198
199
  // is invisible to it.
199
- const ignored = new Set(['tracking', 'records', 'google', 'meta', 'x'])
200
+ const ignored = new Set(['tracking', 'records', 'google', ...AD_PLATFORMS])
200
201
  const has = (ask) => ask.enabled !== false || typeof ask.config?.endpoint === 'string'
201
202
  const unrendered = asks.filter((a) => has(a) && !ignored.has(a.name) && !supports.includes(a.name)).map((a) => a.name)
202
203
  if (unrendered.length) {
@@ -48,12 +48,14 @@ import {
48
48
  collectSiteUnits,
49
49
  collectUnitUuids,
50
50
  collectFolderItemUuids,
51
+ collectFolderRecordTypes,
51
52
  collectQueryUuids,
52
53
  siteItemsByKey,
53
54
  sameServiceRow,
54
55
  heldServices,
55
56
  readBackendState,
56
57
  updateBackendMap,
58
+ setBackendMap,
57
59
  clearBackendSections,
58
60
  normalizeBackendOrigin,
59
61
  harvestRecordItems,
@@ -1327,6 +1329,43 @@ export function writeFolderItemUuids(siteDir, backend, map) {
1327
1329
  if (!map || !Object.keys(map).length) return
1328
1330
  updateBackendMap(siteDir, backend, 'folders', map)
1329
1331
  }
1332
+ /**
1333
+ * What the backend holds each record as — its uuid → the data schema its folder entry names —
1334
+ * banked wherever placements are, from the same folder document. A push reads it to tell a record
1335
+ * whose file moved to another schema (`@uniweb/build`'s `heldTypes`), and sends that record as a
1336
+ * new one in the entry it had.
1337
+ *
1338
+ * ⭐ Written WHOLE, so it names exactly what the folder placed when the backend last handed it back.
1339
+ * That is what tells a push which records it took out of the folder: placed before, not after
1340
+ * (`retireUnplaced`). An entity keeps its schema for life, so the entries never go stale.
1341
+ *
1342
+ * @returns {{ before: Record<string,string>, after: Record<string,string> }}
1343
+ */
1344
+ export function writeHeldTypes(siteDir, backend, folderDoc) {
1345
+ const after = collectFolderRecordTypes(folderDoc)
1346
+ const { prior } = setBackendMap(siteDir, backend, 'types', after)
1347
+ return { before: prior, after }
1348
+ }
1349
+
1350
+ /**
1351
+ * Bank the records this push took out of the site's folder — moved to another schema, or their
1352
+ * files deleted — as `retired`, by uuid, from what the folder placed before the push and after it.
1353
+ * The backend keeps them, in no folder, until they are deleted (`utils/retired-records.js`). A
1354
+ * retired record placed again (a move undone) is dropped from the list.
1355
+ *
1356
+ * ⚠️ Nothing is known before a copy first banks its types, so a copy banked before 2026-11-04
1357
+ * retires nothing on its first push after that.
1358
+ *
1359
+ * @returns {string[]} the uuids this push retired
1360
+ */
1361
+ export function retireUnplaced(siteDir, backend, { before, after }) {
1362
+ const prior = readBackendState(siteDir, backend).retired || {}
1363
+ const now = Object.fromEntries(Object.entries(prior).filter(([uuid]) => !(uuid in after)))
1364
+ const retired = Object.keys(before).filter((uuid) => !(uuid in after))
1365
+ for (const uuid of retired) now[uuid] = before[uuid]
1366
+ setBackendMap(siteDir, backend, 'retired', now)
1367
+ return retired
1368
+ }
1330
1369
  export function writeItemUuids(siteDir, backend, map) {
1331
1370
  if (!map || !Object.keys(map).length) return
1332
1371
  updateBackendMap(siteDir, backend, 'items', map)
@@ -1447,6 +1486,7 @@ export async function recoverRecordsIdentity({ client, siteDir, index, note }) {
1447
1486
  const placements = collectFolderItemUuids(folderDoc)
1448
1487
  const missing = Object.fromEntries(Object.entries(placements).filter(([k]) => !folders[k]))
1449
1488
  writeFolderItemUuids(siteDir, client.origin, missing)
1489
+ writeHeldTypes(siteDir, client.origin, folderDoc)
1450
1490
  const placed = Object.keys(missing).length
1451
1491
  if (matched || placed) {
1452
1492
  note?.(`Recovered the identity of ${matched} record(s) and ${placed} folder placement(s) from the backend.`)
@@ -1457,6 +1497,30 @@ export async function recoverRecordsIdentity({ client, siteDir, index, note }) {
1457
1497
  }
1458
1498
  }
1459
1499
 
1500
+ /**
1501
+ * Read what the backend holds each of the site's records as, from its folder, and bank it
1502
+ * (`writeHeldTypes`). Called when a push was refused for a record changing type, which a copy
1503
+ * that had banked the types would have sent as a move. Best-effort, like
1504
+ * `recoverRecordsIdentity`.
1505
+ *
1506
+ * @returns {Promise<number>} how many records' types were learned
1507
+ */
1508
+ export async function learnHeldTypes({ client, siteDir }) {
1509
+ const siteUuid = readBackendState(siteDir, client.origin).site?.uuid || null
1510
+ if (!siteUuid) return 0
1511
+ try {
1512
+ const res = await client.pullFolder(siteUuid)
1513
+ if (!res?.ok) return 0
1514
+ const docs = entityDocsFromUwx(Buffer.from(await res.arrayBuffer()))
1515
+ const folderDoc = docs.find((d) => d?.$schema === '@uniweb/folder')
1516
+ if (!folderDoc) return 0
1517
+ writeHeldTypes(siteDir, client.origin, folderDoc)
1518
+ return Object.keys(collectFolderRecordTypes(folderDoc)).length
1519
+ } catch {
1520
+ return 0
1521
+ }
1522
+ }
1523
+
1460
1524
  /**
1461
1525
  * The workspace this site was created in on `backend` — its owner, as the create
1462
1526
  * answered it — in the header's form: `@handle`, a unit's bare uuid when that unit has
@@ -2411,41 +2475,51 @@ export async function pushSyncPackages({
2411
2475
  // which is the case this message now names. Suggesting it there sends the
2412
2476
  // user to re-fetch a map they already have.
2413
2477
  if (problem.detail) note(String(problem.detail))
2414
- // ⭐ THE SITE'S FOLDER: one placement per record, keyed by the record it references, so
2415
- // its placements are all new when its records are — every record moved to another data
2416
- // schema, where a record keeps its type and each becomes a new one. The backend cannot
2417
- // tell that from identity lost, so it refuses, and the route is an empty folder first.
2418
- // ⛔ Until 2026-10-29 this said nothing more, and the type-change advice below led here:
2419
- // thirteen gallery records moving from @std/project to their foundation's own schema.
2478
+ // ⭐ THE SITE'S FOLDER: one entry per record. A push finds an entry's `$uuid` by the record
2479
+ // it holds, or by its name when no other entry shares it, so an entry is new only when its
2480
+ // record is new to this backend AND its name is new. A record moved to another schema
2481
+ // keeps its entry while its file keeps its `$uuid` (`heldTypes`, `@uniweb/build`).
2482
+ // ⛔ Until 2026-11-04 this said a placement is new when its record is, and sent the author
2483
+ // to an empty folder first, which left the draft with no records. The refusal it answered
2484
+ // (2026-10-29) came from files renamed as they moved, with their `$uuid` lines deleted.
2420
2485
  if (label === 'records' && where === 'contents') {
2421
2486
  note(
2422
- "That section is the site's folder, one placement per record, and a placement is new when its " +
2423
- 'record is — as when every record has moved to another data schema.'
2487
+ "That section is the site's folder, one entry per record. An entry is found by the record it holds, " +
2488
+ 'or by its name, so records whose files lost their `$uuid` lines and were renamed come back as ' +
2489
+ 'entries that are all new.'
2424
2490
  )
2425
2491
  note(
2426
- 'To replace every record in the folder: push once with the records directory there and holding ' +
2427
- 'nothing at all (the push asks, then removes them), then put the records back and push again.'
2492
+ "Put back each file's `$uuid` line (git has it), then push again: a record moved to another schema " +
2493
+ 'then goes up as a new record, in the place the old one had.'
2494
+ )
2495
+ note(
2496
+ 'To replace every record in the folder with new ones instead, push once with the records directory ' +
2497
+ 'there and holding nothing at all (the push asks, then removes them), then put the records back.'
2428
2498
  )
2429
2499
  }
2430
2500
  return null
2431
2501
  }
2432
- // ⭐ A RECORD KEEPS ITS TYPE. A record file moved to another type's folder keeps its `$uuid`, and
2433
- // the backend refuses it as that type (`type_changed`, naming the record and both types), before
2434
- // writing anything. Storing it as the new type makes it a new record.
2502
+ // ⭐ A RECORD KEEPS ITS TYPE. The backend refuses, before writing anything, a record sent with
2503
+ // its `$uuid` under another type (`type_changed`). A copy that knows what each record is held
2504
+ // as sends a moved one as a new record in the entry it had (`heldTypes`), so this refusal
2505
+ // means this copy had not banked that, as no copy had before 2026-11-04. Learn it from the
2506
+ // folder, and the next push sends the move.
2435
2507
  if (problem?.reason === 'type_changed') {
2436
2508
  error(`${label} push refused — a stored record would change its type.`)
2437
2509
  if (problem.detail) note(String(problem.detail))
2438
- note(
2439
- 'A record keeps its type. To store it as the new type, make it a new record: delete the ' +
2440
- '`$uuid` line from its file, then push again.'
2441
- )
2442
- // ⚠️ Not the whole route when every record of the folder moves at once: each is then new,
2443
- // and so is every placement, which the folder refuses (`identity_required` above).
2444
- note(
2445
- 'Moving every record in the folder to a new type? Then the folder refuses that push too: empty it ' +
2446
- 'first — push once with the records directory there and holding nothing at all — then put the ' +
2447
- 'records back without `$uuid` and push again.'
2448
- )
2510
+ const learned = await learnHeldTypes({ client, siteDir })
2511
+ if (learned) {
2512
+ note(
2513
+ `This copy now knows the type the backend holds each of ${learned} record(s) as. Push again: a ` +
2514
+ 'record moved to another schema then goes up as a new record, in the place the old one had in ' +
2515
+ "the site's folder, and the backend keeps the old one."
2516
+ )
2517
+ } else {
2518
+ note(
2519
+ 'A record keeps its type, so a record moved to another schema goes up as a new one: delete the ' +
2520
+ '`$uuid` line from its file, keep its name for this push, then push again.'
2521
+ )
2522
+ }
2449
2523
  return null
2450
2524
  }
2451
2525
  if (problem?.reason === 'stale_base') {
@@ -2920,6 +2994,8 @@ export async function pushSyncPackages({
2920
2994
  const placements = collectFolderItemUuids(folderDoc)
2921
2995
  if (Object.keys(placements).length)
2922
2996
  writeFolderItemUuids(siteDir, client.origin, placements)
2997
+ // What the folder places now, and so which records this push took out of it.
2998
+ retireUnplaced(siteDir, client.origin, writeHeldTypes(siteDir, client.origin, folderDoc))
2923
2999
  // ⭐ A LINK RECORD'S IDENTITY is its folder entry's `$uuid`, banked as a record's is: into
2924
3000
  // its file the first time, then mapped per backend (`link-records.js`, 2026-09-28).
2925
3001
  if (records.links?.length) {
@@ -89,7 +89,8 @@ import {
89
89
  describeSyncedElsewhere
90
90
  } from '../utils/site-identity.js'
91
91
  import { isNonInteractive, confirm } from '../utils/interactive.js'
92
- import { guardEmptyRecords, noteFolderLeftAlone } from '../utils/records-guard.js'
92
+ import { guardEmptyRecords, noteFolderLeftAlone, noteMovedRecords } from '../utils/records-guard.js'
93
+ import { settleRetiredRecords } from '../utils/retired-records.js'
93
94
  import { findSiteCopies, describeSiteCopies } from '../utils/site-copies.js'
94
95
  import { headProvenance } from '../utils/git.js'
95
96
  import {
@@ -988,6 +989,7 @@ export async function publish(args = []) {
988
989
  for (const w of pkg.warnings) say.dim(`! ${w}`)
989
990
  // A folder this publish leaves alone while the backend's still holds records — see `uniweb push`.
990
991
  await noteFolderLeftAlone({ pkg, siteDir, backend: client.origin, note: (m) => say.dim(m) })
992
+ noteMovedRecords({ pkg, siteDir, note: (m) => say.dim(m) })
991
993
  if (refuseUnsendableRecords(pkg.refusals, { error: say.err, note: say.dim })) {
992
994
  return { exitCode: 1 }
993
995
  }
@@ -1176,6 +1178,9 @@ export async function publish(args = []) {
1176
1178
  // `lastDeploy.<target>.url` (step 8 above). site.yml carried it as `$url` ⇄
1177
1179
  // `info.url` from 2026-09-10 until the field was retired on 2026-09-17.
1178
1180
  if (result.deploy_uuid) say.dim(`deploy: ${result.deploy_uuid}`)
1181
+ // ⭐ The records this publish's push took out of the site's folder: the CLI offers to delete them
1182
+ // from the backend (ruled 2026-11-04; `utils/retired-records.js`).
1183
+ await settleRetiredRecords({ client, siteDir, args, say })
1179
1184
  return { exitCode: 0 }
1180
1185
  }
1181
1186
 
@@ -108,6 +108,7 @@ import {
108
108
  reportWriteBacks,
109
109
  writeItemUuids,
110
110
  writeFolderItemUuids,
111
+ writeHeldTypes,
111
112
  readItemBaseVersions
112
113
  } from '../backend/site-sync.js'
113
114
  import { resolveWorkspace } from '../backend/workspace.js'
@@ -1220,6 +1221,8 @@ export async function pull(args = [], deps = {}) {
1220
1221
  // and the backend refused that push (`identity_required`, section `contents`) —
1221
1222
  // measured on a template clone's first edit.
1222
1223
  if (folderDoc) writeFolderItemUuids(projDir, client.origin, collectFolderItemUuids(folderDoc))
1224
+ // …and what each record is held as, so a push can tell a record whose file moved schema.
1225
+ if (folderDoc) writeHeldTypes(projDir, client.origin, folderDoc)
1223
1226
  // The folder's organization, `folder.yml` in the records directory — named as
1224
1227
  // the author would write it (`records/folder.yml`, or under `paths.records`).
1225
1228
  if (report.records === 'updated') {
@@ -79,7 +79,8 @@ import {
79
79
  } from '../utils/site-identity.js'
80
80
  import { confirm, isNonInteractive } from '../utils/interactive.js'
81
81
  import { announceServices, foundationSupports } from '../backend/service-request.js'
82
- import { guardEmptyRecords, noteFolderLeftAlone } from '../utils/records-guard.js'
82
+ import { guardEmptyRecords, noteFolderLeftAlone, noteMovedRecords } from '../utils/records-guard.js'
83
+ import { settleRetiredRecords } from '../utils/retired-records.js'
83
84
  import { bringFoundationAlong, filesAReleaseWrites } from '../backend/foundation-bring-along.js'
84
85
  import { repoOf } from '../utils/sync-point.js'
85
86
  import {
@@ -639,6 +640,8 @@ export async function push(args = [], deps = {}) {
639
640
  // A folder this push leaves alone while the backend's still holds records — said, since an author
640
641
  // who took the records out expects them gone (`noteFolderLeftAlone`).
641
642
  await noteFolderLeftAlone({ pkg, siteDir, backend: client.origin, note })
643
+ // Records whose files moved to another data schema go up as new records in the entries they had.
644
+ noteMovedRecords({ pkg, siteDir, note })
642
645
  // The same stop for the paths the probe above does not run on — `-o` and
643
646
  // `--dry-run` say what a push would do, and a push would stop here.
644
647
  if (refuseUnsendableRecords(pkg.refusals, { error, note })) return { exitCode: 1 }
@@ -731,5 +734,8 @@ export async function push(args = [], deps = {}) {
731
734
  (result.wrote.length ? ` — ${result.wrote.join(', ')}` : '')
732
735
  )
733
736
  reportWriteBacks(written, { note })
737
+ // ⭐ The records this push took out of the site's folder are off the live site already (it reads
738
+ // its folder as it stands): offer to delete them from the backend (ruled 2026-11-04).
739
+ await settleRetiredRecords({ client, siteDir, args, say: { ok: success, dim: note, warn: note } })
734
740
  return { exitCode: 0 }
735
741
  }
@@ -4,8 +4,11 @@
4
4
  * uniweb site list [--json] each site's name, uuid, and whether it is live
5
5
  * uniweb site unpublish [<site-uuid>] [--yes] take a site offline; its content stays
6
6
  * uniweb site delete [<site-uuid>] [--yes] delete a site — final, no restore
7
+ * uniweb site secret <service> <name> [<site-uuid>] set a secret a service uses;
8
+ * it asks for the value
9
+ * uniweb site secret <service> <name> --clear [<site-uuid>] clear it
7
10
  *
8
- * Without a uuid, `unpublish` and `delete` act on the site this project is synced to on
11
+ * Without a uuid, `unpublish`, `delete` and `secret` act on the site this project is synced to on
9
12
  * that backend. The workspace is the command's (`--org @x` / `--personal`), else the
10
13
  * login's — as for every site request.
11
14
  *
@@ -28,6 +31,7 @@ import { join, resolve } from 'node:path'
28
31
  import { BackendClient, WorkspaceMismatchError, describeWorkspace } from '../backend/client.js'
29
32
  import { resolveWorkspace } from '../backend/workspace.js'
30
33
  import { liveAddress } from '../backend/live-address.js'
34
+ import { AD_PLATFORMS } from '../backend/ad-platforms.js'
31
35
  import { checkFlags } from '../utils/flag-guard.js'
32
36
  import { confirm, isNonInteractive } from '../utils/interactive.js'
33
37
  import { readSiteIdentity } from '../utils/site-identity.js'
@@ -57,8 +61,14 @@ const USAGE = [
57
61
  ' list [--json] The sites in the workspace: name, uuid, whether live',
58
62
  ' unpublish [<site-uuid>] [--yes] Take a site offline (its content stays)',
59
63
  ' delete [<site-uuid>] [--yes] Delete a site — final',
64
+ ' secret <service> <name> [<site-uuid>]',
65
+ ' Set a secret a service of the site uses (an ad',
66
+ " platform's token: secret x token). It asks for",
67
+ ' the value, which no argument or file carries',
68
+ ' secret <service> <name> --clear [<site-uuid>]',
69
+ ' Clear it',
60
70
  '',
61
- 'Without a uuid, unpublish and delete act on the site this project is synced to.',
71
+ 'Without a uuid, unpublish, delete and secret act on the site this project is synced to.',
62
72
  'The workspace is --org @x or --personal, else the one chosen at login.'
63
73
  ].join('\n')
64
74
 
@@ -160,8 +170,8 @@ async function list(args) {
160
170
  * The site a write verb acts on: the uuid given, else this project's site on the
161
171
  * backend the client goes to. Null, with the reason said, when there is neither.
162
172
  */
163
- async function targetSite(args, client, verb) {
164
- const [, given] = positionals(args)
173
+ async function targetSite(args, client, verb, at = 1) {
174
+ const given = positionals(args)[at]
165
175
  if (given) {
166
176
  if (!UUID.test(given)) {
167
177
  say.err(`\`${given}\` is not a site uuid.`)
@@ -332,6 +342,135 @@ async function remove(args) {
332
342
  return { exitCode: 0 }
333
343
  }
334
344
 
345
+ /**
346
+ * The secret's value, typed by the person running the command at a prompt that doesn't show it.
347
+ * `{ refused: true }` when there is nobody to ask; `{ value: '' }` when they typed nothing.
348
+ */
349
+ async function askSecretValue(args, label) {
350
+ if (isNonInteractive(args)) return { refused: true }
351
+ const prompts = (await import('prompts')).default
352
+ let cancelled = false
353
+ const { value } = await prompts(
354
+ { type: 'password', name: 'value', message: `${label}:`, stdout: process.stderr },
355
+ { onCancel: () => (cancelled = true) }
356
+ )
357
+ return { value: cancelled || typeof value !== 'string' ? '' : value }
358
+ }
359
+
360
+ /** What a `400 invalid_field` said, in words: the body key and why. */
361
+ function invalidField(body) {
362
+ const why = {
363
+ required: 'is required',
364
+ one_of: 'is not one the backend takes',
365
+ required_when: 'must name the service it is for',
366
+ renamed_service: 'names a retired service',
367
+ }
368
+ return `the ${body.field} ${why[body.reason] || `was refused (${body.reason})`}`
369
+ }
370
+
371
+ /**
372
+ * `uniweb site secret <service> <name> [<site-uuid>]` — set a secret one of the site's services
373
+ * uses, its value typed at a prompt that doesn't show it. `--clear` removes it.
374
+ *
375
+ * ⛔ THE VALUE COMES FROM THE PERSON AT A TERMINAL, NEVER FROM AN ARGUMENT, A FILE OR A PIPE. An
376
+ * argument lands in shell history and in an agent's transcript, a file is a copy left behind, and
377
+ * a pipe is how an agent would pass one on. So with no terminal the command refuses and says who
378
+ * runs it. A fourth argument that is not a site uuid may be the value itself, so it is never
379
+ * echoed.
380
+ *
381
+ * ⭐ An ad platform's token is for the host, which sends the site's conversions on with it
382
+ * (`AD_PLATFORMS`), so for those the request names the host as the secret's reader. For any other
383
+ * service it names none: the backend keeps the reader a secret already has, and a new one is the
384
+ * site's own.
385
+ *
386
+ * A set or a clear reaches the live site at its next publish, so the command says to publish.
387
+ *
388
+ * @param {string[]} args
389
+ * @param {{ readValue?: (args: string[], label: string) => Promise<{ value?: string, refused?: boolean }> }} [io]
390
+ */
391
+ export async function siteSecret(args, { readValue = askSecretValue } = {}) {
392
+ const [, service, name, siteArg, ...extra] = positionals(args)
393
+ const clear = args.includes('--clear')
394
+ if (!service || !name) {
395
+ say.err('Name the service and the secret: uniweb site secret <service> <name>, e.g. uniweb site secret x token')
396
+ return { exitCode: 2 }
397
+ }
398
+ if ((siteArg && !UUID.test(siteArg)) || extra.length) {
399
+ say.err('`uniweb site secret` takes a service, a name and, optionally, a site uuid — nothing else.')
400
+ say.dim("A secret's value is never given on the command line: the command asks for it.")
401
+ say.dim('If what you typed was the value, it is now in your shell history: replace it where it was issued.')
402
+ return { exitCode: 2 }
403
+ }
404
+ const what = `${service}'s ${name}`
405
+ const conn = await connect(args, clear ? 'Clearing a secret' : 'Setting a secret')
406
+ if (conn.refused) {
407
+ say.err(conn.refused)
408
+ return { exitCode: 2 }
409
+ }
410
+ const { client } = conn
411
+ const target = await targetSite(args, client, `secret ${service} ${name}${clear ? ' --clear' : ''}`, 3)
412
+ if (!target) return { exitCode: 2 }
413
+ const listed = await findSite(client, target.uuid)
414
+ const label = listed?.name ? `“${listed.name}” (${target.uuid})` : target.uuid
415
+ const forHost = AD_PLATFORMS.has(service)
416
+
417
+ let res
418
+ if (clear) {
419
+ const ok = await confirmed(
420
+ args,
421
+ `Clear ${what} on ${label}, on ${client.origin}? The live site keeps it until its next publish.`,
422
+ `secret ${service} ${name} --clear`
423
+ )
424
+ if (!ok.yes) return { exitCode: ok.exitCode }
425
+ res = await client.clearSiteSecret(target.uuid, { service, name })
426
+ } else {
427
+ const typed = await readValue(args, `${what} for ${label}`)
428
+ if (typed.refused) {
429
+ say.err('`uniweb site secret` asks for the value, and there is no terminal here to ask in.')
430
+ // The line to run, as this one was given: its site uuid and workspace, never a value.
431
+ const org = args.indexOf('--org')
432
+ const again = [
433
+ 'uniweb site secret', service, name,
434
+ ...(siteArg ? [siteArg] : []),
435
+ ...(org !== -1 && args[org + 1] ? ['--org', args[org + 1]] : []),
436
+ ...(args.includes('--personal') ? ['--personal'] : []),
437
+ ].join(' ')
438
+ say.dim(`A person runs it, in a terminal: ${again}`)
439
+ return { exitCode: 2 }
440
+ }
441
+ if (!typed.value) {
442
+ say.info('Nothing typed — nothing changed.')
443
+ return { exitCode: 0 }
444
+ }
445
+ res = await client.setSiteSecret(target.uuid, {
446
+ service,
447
+ name,
448
+ ...(forHost ? { consumer: 'hosting' } : {}),
449
+ value: typed.value,
450
+ })
451
+ }
452
+
453
+ if (!res.ok) {
454
+ const body = await res.clone().json().catch(() => null)
455
+ if (res.status === 400 && body?.reason && body?.field) {
456
+ say.err(`The backend refused it: ${invalidField(body)}.`)
457
+ } else if (res.status === 404 && listed) {
458
+ say.err(`${client.origin} lists this site but answered 404 to its secret — it may run a backend older than this command.`)
459
+ } else {
460
+ await sayRefusal(res, { uuid: target.uuid, verb: clear ? 'clear a secret on' : 'set a secret on', origin: client.origin })
461
+ }
462
+ return { exitCode: 1 }
463
+ }
464
+ const body = await res.json().catch(() => null)
465
+ if (clear) {
466
+ say.ok(`Cleared ${what} on ${label}.`)
467
+ } else {
468
+ say.ok(`Set ${what} on ${label}${body?.mask ? `: ${body.mask}` : ''}${forHost ? ', for your host to use' : ''}.`)
469
+ }
470
+ say.dim('The live site has it from its next publish: uniweb publish')
471
+ return { exitCode: 0 }
472
+ }
473
+
335
474
  export async function site(args = []) {
336
475
  const badFlag = checkFlags('site', args)
337
476
  if (badFlag) {
@@ -343,6 +482,7 @@ export async function site(args = []) {
343
482
  if (sub === 'list') return await list(args)
344
483
  if (sub === 'unpublish') return await unpublish(args)
345
484
  if (sub === 'delete') return await remove(args)
485
+ if (sub === 'secret') return await siteSecret(args)
346
486
  } catch (err) {
347
487
  say.err(err instanceof WorkspaceMismatchError ? err.message : err?.message || String(err))
348
488
  return { exitCode: 1 }
@@ -88,6 +88,7 @@ import { classifyPackage, findSites, findWorkspaceRoot, isWorkspaceRoot } from '
88
88
  import { siteAround } from '../utils/pick-site.js'
89
89
  import { getCliVersion } from '../versions.js'
90
90
  import { planNext } from '../utils/status-next.js'
91
+ import { AD_PLATFORMS } from '../backend/ad-platforms.js'
91
92
 
92
93
  const c = {
93
94
  reset: '\x1b[0m',
@@ -1397,11 +1398,12 @@ const list = (names) => names.map((n) => `\`${n}\``).join(', ')
1397
1398
 
1398
1399
  /**
1399
1400
  * Asked for, and never among what a publish reports delivering (`last_published_services`):
1400
- * a host loads Google's tag, so nothing answers at an address and nothing is sold. By that
1401
- * comparison it would read "not live yet" for ever, and send an agent back to publish. A row
1402
- * changed since the last publish still says so, as `draft_dirty`.
1401
+ * a host loads Google's tag, so nothing answers at an address and nothing is sold; and `x` and
1402
+ * `meta` reach the host in the site's credentials map, which that list never names [backend,
1403
+ * 2026-11-03]. By that comparison each would read "not live yet" for ever, and send an agent back
1404
+ * to publish. A row changed since the last publish still says so, as `draft_dirty`.
1403
1405
  */
1404
- const NOT_REPORTED_AS_LIVE = new Set(['google'])
1406
+ const NOT_REPORTED_AS_LIVE = new Set(['google', ...AD_PLATFORMS])
1405
1407
 
1406
1408
  /**
1407
1409
  * `app.services`: what `site.yml` asks for, beside what the backend holds — the request it
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-03T21:24:25.282Z",
3
+ "generatedAt": "2026-11-04T04:02:52.879Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.15.2"
9
+ "version": "1.15.3"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.8"
@@ -15,7 +15,7 @@
15
15
  "version": "1.3.1"
16
16
  },
17
17
  "@uniweb/core": {
18
- "version": "1.6.3"
18
+ "version": "1.6.4"
19
19
  },
20
20
  "@uniweb/frame-bridge": {
21
21
  "version": "1.0.3"
@@ -24,7 +24,7 @@
24
24
  "version": "1.0.8"
25
25
  },
26
26
  "@uniweb/kit": {
27
- "version": "1.7.8"
27
+ "version": "1.7.9"
28
28
  },
29
29
  "@uniweb/loom": {
30
30
  "version": "1.1.3"
@@ -36,7 +36,7 @@
36
36
  "version": "1.2.11"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.4.2"
39
+ "version": "1.4.4"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
package/src/index.js CHANGED
@@ -2032,7 +2032,8 @@ ${colors.bright}Usage:${colors.reset}
2032
2032
  uniweb push [options]
2033
2033
 
2034
2034
  Sends the site's content to the backend you are logged in to, releasing the local
2035
- foundation first if its code changed. The site is not live until \`uniweb publish\`.
2035
+ foundation first if its code changed. Its pages go live with \`uniweb publish\`. Its
2036
+ records are live at once on a site already published, which reads them from its folder.
2036
2037
 
2037
2038
  In a git repository a push sends what is committed. It is refused, with nothing
2038
2039
  written, if the site changed in the app since your last pull: run \`uniweb pull\` to
@@ -2104,15 +2105,21 @@ ${colors.bright}Usage:${colors.reset}
2104
2105
  uniweb site list [--json]
2105
2106
  uniweb site unpublish [<site-uuid>] [--yes]
2106
2107
  uniweb site delete [<site-uuid>] [--yes]
2108
+ uniweb site secret <service> <name> [<site-uuid>]
2109
+ uniweb site secret <service> <name> --clear [<site-uuid>] [--yes]
2107
2110
 
2108
2111
  ${colors.bright}list${colors.reset} gives each site's name, uuid, and whether it is live.
2109
2112
  ${colors.bright}unpublish${colors.reset} takes a site offline, and its content stays.
2110
2113
  ${colors.bright}delete${colors.reset} removes a site for good. A live site must be unpublished first.
2111
-
2112
- Without a uuid, \`unpublish\` and \`delete\` act on the site this project is synced to.
2113
- Both ask first, and \`--yes\` is the only way past the question: with no terminal and
2114
- no \`--yes\` they refuse. Deleting this project's own site also forgets it here, so the
2115
- next push creates a new one.
2114
+ ${colors.bright}secret${colors.reset} sets a secret one of the site's services uses, such as an ad platform's
2115
+ token (\`uniweb site secret x token\`). It asks for the value at a prompt that doesn't
2116
+ show it: no argument or file carries one, and with no terminal it refuses. The live
2117
+ site has it from its next publish. \`--clear\` removes it.
2118
+
2119
+ Without a uuid, \`unpublish\`, \`delete\` and \`secret\` act on the site this project is synced to.
2120
+ \`unpublish\`, \`delete\` and \`secret --clear\` ask first, and \`--yes\` is the only way
2121
+ past the question: with no terminal and no \`--yes\` they refuse. Deleting this
2122
+ project's own site also forgets it here, so the next push creates a new one.
2116
2123
 
2117
2124
  ${colors.bright}Options:${colors.reset}
2118
2125
  --json \`list\`: print JSON
@@ -104,10 +104,11 @@ const VERBS = {
104
104
  */
105
105
  forget: ['--server', '--all'],
106
106
  /**
107
- * `site list | unpublish | delete` — a workspace's sites. `--yes` confirms a write;
108
- * `--json` is `list`'s porcelain; the workspace is `--org` / `--personal`.
107
+ * `site list | unpublish | delete | secret` — a workspace's sites. `--yes` confirms a write;
108
+ * `--json` is `list`'s porcelain; `--clear` makes `secret` remove one; the workspace is
109
+ * `--org` / `--personal`.
109
110
  */
110
- site: ['--json', '--yes', '--org', '--personal'],
111
+ site: ['--json', '--yes', '--clear', '--org', '--personal'],
111
112
  status: [
112
113
  '--json', '--offline', '--dry-run',
113
114
  '--force', '--no-verify', '--no-validate', '--yes', '--org', '--personal',
@@ -19,6 +19,7 @@
19
19
  // last saw the folder hold. It needs no network call, and it is the right source:
20
20
  // a site that has never pushed has nothing to lose and is never asked.
21
21
 
22
+ import { relative } from 'node:path'
22
23
  import { readEntityPool } from '@uniweb/build/uwx'
23
24
  import { readFolderItemUuids } from '../backend/site-sync.js'
24
25
  import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
@@ -120,3 +121,40 @@ export async function noteFolderLeftAlone({ pkg, siteDir, backend, note }) {
120
121
  )
121
122
  return count
122
123
  }
124
+
125
+ /**
126
+ * Say which records this push moves to another data schema, and what that does.
127
+ *
128
+ * A record whose file now sits under another schema than the one the backend holds it as goes up
129
+ * as a new record of the new schema, in the folder entry the old one had (`heldTypes`,
130
+ * `@uniweb/build`). The backend keeps the old record, in no folder, so no site serves it. A field
131
+ * the file holds as `#ref`, a set secret, arrives unset on the new record [backend, 2026-11-04].
132
+ *
133
+ * @param {object} params
134
+ * @param {object} params.pkg - what `emitSyncPackages` returned
135
+ * @param {string} params.siteDir
136
+ * @param {(m: string) => void} params.note - the caller's reporter
137
+ * @returns {number} how many records move
138
+ */
139
+ export function noteMovedRecords({ pkg, siteDir, note }) {
140
+ const moved = (pkg?.records?.index || []).filter((e) => e?.moved)
141
+ if (!moved.length) return 0
142
+ const where = (e) => (e.sourceFile ? relative(siteDir, e.sourceFile) : e.id)
143
+ const one = moved.length === 1
144
+ note(
145
+ `↻ ${one ? 'A record moves' : `${moved.length} records move`} to another schema: ${one ? 'it goes' : 'each goes'} ` +
146
+ `up as a new record, in the place the old one had in the site's folder.`
147
+ )
148
+ for (const e of moved) note(` ${where(e)}: ${e.moved.from} → ${e.moved.to}`)
149
+ note(` The backend keeps the old ${one ? 'record' : 'records'}, in no folder, so no site serves ${one ? 'it' : 'them'}.`)
150
+ for (const e of moved) {
151
+ const secrets = e.moved.secrets || []
152
+ if (secrets.length) {
153
+ note(
154
+ ` ! ${where(e)}: ${secrets.map((s) => `\`${s}\``).join(', ')} ${secrets.length === 1 ? 'holds a secret' : 'hold secrets'}, ` +
155
+ 'which stay with the old record. Set them again on the new one, in the app.'
156
+ )
157
+ }
158
+ }
159
+ return moved.length
160
+ }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * The records this copy's pushes took out of the site's folder — moved to another data schema, or
3
+ * their files deleted — which the backend keeps, in no folder, until someone deletes them
4
+ * (`sync.json` `retired`, banked by `retireUnplaced` in `backend/site-sync.js`).
5
+ *
6
+ * ⭐ RULED 2026-11-04 [Diego]: the CLI deletes them, asking first with a count, rather than leaving
7
+ * the cleanup to the app — agents do most of the work through the CLI. The backend's route keeps a
8
+ * record that a folder outside the call still places (another site's), and names it.
9
+ *
10
+ * ⭐ ASKED AT THE END OF THE PUSH THAT RETIRED THEM, and of a publish, which pushes. A published
11
+ * site reads its records from its folder as the folder stands, with no snapshot taken at publish, so
12
+ * the push has already taken them off the live site [backend, 2026-11-04 —
13
+ * `backend/docs/delivery-orientation.md`: "Adding a blog post updates the live site with no
14
+ * republish"]. ⛔ Until then this asked only at publish, "because until then the live site still has
15
+ * the folder that placed them", which is not how that wire behaves. It also meant a site whose author
16
+ * pushes its records and never publishes again was never asked.
17
+ *
18
+ * As emptying the folder does, it asks first, and `--yes` is the way past the question. With no
19
+ * terminal and no `--yes`, it keeps them and says how to finish. A person who declines keeps them,
20
+ * and is not asked again.
21
+ */
22
+
23
+ import { readBackendState, setBackendMap } from '@uniweb/build/uwx'
24
+ import { confirm, isNonInteractive } from './interactive.js'
25
+
26
+ /** "2 records (of @std/project)", or by schema: "3 records (2 of @std/project, 1 of @acme/x)". */
27
+ function describeRetired(retired) {
28
+ const bySchema = new Map()
29
+ for (const schema of Object.values(retired)) bySchema.set(schema, (bySchema.get(schema) || 0) + 1)
30
+ const n = Object.keys(retired).length
31
+ const groups = [...bySchema].map(([schema, k]) => (bySchema.size === 1 ? `of ${schema}` : `${k} of ${schema}`))
32
+ return `${n === 1 ? '1 record' : `${n} records`} (${groups.join(', ')})`
33
+ }
34
+
35
+ /**
36
+ * After a push, or a publish: offer to delete the retired records, and delete them on a yes.
37
+ *
38
+ * @param {object} params
39
+ * @param {object} params.client - a `BackendClient` on the site's backend, in its workspace
40
+ * @param {string} params.siteDir
41
+ * @param {string[]} params.args - the command's arguments (`--yes`, `--non-interactive`)
42
+ * @param {{ ok: Function, dim: Function, warn: Function }} params.say
43
+ * @param {(question: string, defaultYes: boolean) => Promise<boolean>} [params.ask]
44
+ * @returns {Promise<{ deleted: number, kept: number, asked: boolean }>}
45
+ */
46
+ export async function settleRetiredRecords({ client, siteDir, args = [], say, ask = confirm }) {
47
+ const retired = readBackendState(siteDir, client.origin).retired || {}
48
+ const uuids = Object.keys(retired)
49
+ if (!uuids.length) return { deleted: 0, kept: 0, asked: false }
50
+ const what = describeRetired(retired)
51
+ const forget = (done) =>
52
+ setBackendMap(siteDir, client.origin, 'retired', Object.fromEntries(Object.entries(retired).filter(([u]) => !done.includes(u))))
53
+
54
+ if (!args.includes('--yes')) {
55
+ if (isNonInteractive(args)) {
56
+ say.dim(
57
+ `! ${what} that pushes took out of the site's folder stay on the backend, where no site serves them. ` +
58
+ 'To delete them, push again with --yes, or from a terminal and answer.'
59
+ )
60
+ return { deleted: 0, kept: uuids.length, asked: false }
61
+ }
62
+ const yes = await ask(
63
+ `Delete ${what} that pushes took out of the site's folder from ${client.origin}? A record another site's folder places is kept.`,
64
+ false
65
+ )
66
+ if (!yes) {
67
+ forget(uuids)
68
+ say.dim('Kept them on the backend, where no site serves them. They are not asked about again.')
69
+ return { deleted: 0, kept: uuids.length, asked: true }
70
+ }
71
+ }
72
+
73
+ let res
74
+ try {
75
+ res = await client.deleteEntities({ uuids, placed: 'keep' })
76
+ } catch (err) {
77
+ say.warn(`Could not delete them: ${err?.message || err}. They stay on the backend; the next push asks again.`)
78
+ return { deleted: 0, kept: uuids.length, asked: true }
79
+ }
80
+ if (res.status === 404) {
81
+ // A backend older than its delete route: they wait for one that has it.
82
+ say.dim(`! ${client.origin} cannot delete records from the CLI yet, so they stay, where no site serves them.`)
83
+ return { deleted: 0, kept: uuids.length, asked: true }
84
+ }
85
+ const body = await res.json().catch(() => null)
86
+ if (!res.ok) {
87
+ // Refused whole (a record this account may not administer, or one outside the workspace):
88
+ // nothing was deleted, and asking again would be refused again.
89
+ say.warn(
90
+ `${client.origin} did not delete them: HTTP ${res.status}${body?.detail ? ` — ${body.detail}` : ''}. ` +
91
+ 'They stay on the backend, where no site serves them; delete them in the app if they should go.'
92
+ )
93
+ forget(uuids)
94
+ return { deleted: 0, kept: uuids.length, asked: true }
95
+ }
96
+ const deleted = Array.isArray(body?.deleted) ? body.deleted : []
97
+ const kept = Array.isArray(body?.kept) ? body.kept : []
98
+ if (deleted.length) say.ok(`Deleted ${deleted.length === 1 ? '1 record' : `${deleted.length} records`} from the backend.`)
99
+ if (kept.length) {
100
+ say.dim(`Kept ${kept.length === 1 ? '1 record' : `${kept.length} records`}: another site's folder still places ${kept.length === 1 ? 'it' : 'them'}.`)
101
+ }
102
+ // Every uuid is settled: deleted, kept for another folder, or naming nothing any more.
103
+ forget(uuids)
104
+ return { deleted: deleted.length, kept: kept.length, asked: true }
105
+ }