uniweb 0.33.1 → 0.34.0

package/src/utils/records-guard.js

@@ -0,0 +1,80 @@
+// ⛔ THE ONE PLACE AN ORDINARY ACT IS DESTRUCTIVE.
+//
+// `records.yml` is the sync control, and `missing` and `empty` deliberately mean
+// different things: missing leaves the server's folder untouched, empty says the
+// folder holds nothing and the backend removes what is there. The asymmetry is
+// well-shaped — the safe state is the ABSENCE of a file, so a live folder cannot
+// be wiped by deleting one, and the destructive act requires affirmatively
+// creating one.
+//
+// ⚠️ WHICH LEAVES EXACTLY ONE SHARP EDGE: a PLACEHOLDER. Someone creates an empty
+// `records.yml` intending to fill it in, pushes, and the live folder empties.
+// That is plausible and it is the only path where a normal act destroys content.
+//
+// ⭐ THE FORMAT STAYS HONEST AND THE CLI DOES THE ASKING. Never make "empty" mean
+// "missing" to dodge this: that would delete a capability to avoid writing a
+// prompt.
+//
+// The count comes from the placement identity a previous push banked — what WE
+// last saw the folder hold. It needs no network call, and it is the right source:
+// a site that has never pushed has nothing to lose and is never asked.
+
+import { readRecordsConfig, FOLDER_EMPTY } from '@uniweb/build/uwx'
+import { readFolderItemUuids } from '../backend/site-sync.js'
+import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
+
+/**
+ * Leaf placements in a banked path→uuid map.
+ *
+ * A branch's path is a prefix of every path beneath it, so anything that is a
+ * prefix of another key is a folder rather than a record. Counting raw keys would
+ * report a two-record site inside one folder as three things to lose.
+ */
+export function countPlacedRecords(pathToUuid) {
+  const paths = Object.keys(pathToUuid || {})
+  return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(`${p}/`))).length
+}
+
+/**
+ * Stop an empty `records.yml` from silently emptying a live folder.
+ *
+ * @param {object} params
+ * @param {string} params.siteDir
+ * @param {string[]} params.args - the verb's argv, for --yes / non-interactive
+ * @param {(m: string) => void} params.warn - the CALLER's reporter. Each verb owns
+ *        its own output style; a second copy here would drift from all of them.
+ * @param {(m: string) => void} params.note
+ * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
+ */
+export async function guardEmptyRecords({ siteDir, args = [], warn, note }) {
+  const cfg = await readRecordsConfig(siteDir)
+  if (cfg.state !== FOLDER_EMPTY) return { ok: true, count: 0 }
+
+  const count = countPlacedRecords(readFolderItemUuids(siteDir))
+  // Nothing banked ⇒ nothing this push can remove. A first push of an empty
+  // folder is a legitimate (if odd) thing to do, and asking about it would train
+  // people to type y.
+  if (count === 0) return { ok: true, count: 0 }
+
+  warn(
+    `records.yml is empty, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the live folder.`
+  )
+  note(
+    'An empty records.yml means "the folder holds nothing" — it is not the same as ' +
+      'having no records.yml, which leaves the live folder alone. If you meant to ' +
+      'start listing records, delete the file until you have.'
+  )
+
+  // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
+  // would have been caught by `flag-guard-coverage.test.js` — which it was.
+  if (args.includes('--yes')) return { ok: true, count }
+  if (isNonInteractive(args)) {
+    warn(`Refusing to remove ${count} record${count === 1 ? '' : 's'} without confirmation.`)
+    note(`Re-run with --yes if that is what you want: ${getCliPrefix()} push --yes`)
+    return { ok: false, count }
+  }
+
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the live folder?`, false)
+  return { ok: yes, count }
+}

package/src/utils/schemaless-report.js

@@ -1,5 +1,5 @@
 /**
- * Report collections publishing without a data schema.
+ * Report queries publishing without a data schema.
  *
  * ⭐ This is a PRODUCT decision the author is making, usually without knowing:
  * entities or static files. It is reported at warn level for that reason — the
@@ -14,10 +14,10 @@
  * @param {Array<{name: string, model?: string}>} schemaless
  * @param {{ warn: (m: string) => void, dim: (m: string) => void }} out
  */
-export function reportSchemalessCollections(schemaless, out) {
+export function reportSchemalessQueries(schemaless, out) {
   if (!schemaless?.length) return
   const names = schemaless.map((c) => c.name)
-  const label = names.length === 1 ? 'collection' : 'collections'
+  const label = names.length === 1 ? 'query' : 'queries'
   out.warn(
     `${names.length} ${label} shipping as STATIC FILES, not entities: ${names.join(', ')}`
   )
@@ -25,6 +25,6 @@ export function reportSchemalessCollections(schemaless, out) {
   out.dim(
     `Declare a data schema to get entities. Each resolves its schema by subfolder name (${schemaless
       .map((c) => `${c.name} → ${c.model || c.name}`)
-      .join(', ')}), or set \`schema:\` on the collection.`
+      .join(', ')}), or set \`schema:\` on the query.`
   )
 }

package/src/utils/site-data-upload.js

@@ -1,7 +1,7 @@
 /**
  * Static collection data — the passthrough lane.
  *
- * A site's **schema-less** collections have no entity model, so their compiled
+ * A site's **schema-less** queries have no entity model, so their compiled
  * `dist/data/**` JSON is delivered as files rather than synced as entities.
  * This plans and uploads that set: one plan call, one object per file, each
  * PUT to the target the backend returns.
@@ -93,7 +93,7 @@ export async function uploadSiteData({
       //
       // ⛔ And the failure is INVISIBLE from here: the plan succeeds, the PUT
       // succeeds, and only a visitor's fetch 404s. Confirmed against the
-      // shipped contract's own example (`collections/articles.json` with a
+      // shipped contract's own example (`data/articles.json` with a
       // `/data/`-bearing `serve_base`), which supersedes an earlier
       // parenthetical that showed the prefix.
       path: relPath,

package/templates/site/site.yml.hbs

@@ -25,20 +25,38 @@ index: home
 #   pages/docs: ../../../docs       # Mount docs repo at /docs route
 #   pages/blog: ../../blog-content  # Mount blog content at /blog route
 #   layout: ./custom-layout         # Custom layout directory
-#   collections: ./data             # Collections directory
+#   entities: ./data                # Where this site's entities live
 #
 # To give a mounted route a layout or a title, add a local folder for it
 # (pages/docs/) holding a folder.yml — folder.yml, not page.yml, because the
 # mounted directory is a folder of pages. Whatever that stub leaves unset comes
 # from the mounted directory's own folder.yml, so it need only say what differs.
 
-# ─── Data Sources ─────────────────────────────────────────────────────────────
-# Define collections (local markdown folders) or fetch remote/local JSON data.
-# Pages and sections reference sources by name via `data: source-name`.
+# ─── Structured Content ───────────────────────────────────────────────────────
+# Three things, and they are separate on purpose:
 #
-# collections:
+#   entities/{schema}/   your stored records. The folder names their data schema:
+#                          entities/article/       → @/article  (your foundation's)
+#                          entities/std/person/    → @std/person
+#   records.yml          WHAT IS PUBLISHED. Listing an entity here is what makes it
+#                        a record; anything you leave out is a draft. Usually three
+#                        lines:
+#                            - article/*.md
+#                            - person/*.md
+#   queries.yml          HOW CONTENT IS REACHED — named queries over those records:
+#                            recent:
+#                              schema: '@/article'
+#                              sort: date desc
+#                              limit: 10
+#
+# Pages and sections then name a query: `data: recent`, or
+# `fetch: { query: recent }`.
+#
+# You can also keep queries here instead of in queries.yml:
+#
+# queries:
 #   articles:
-#     path: collections/articles         # Folder of .md entity files
+#     schema: '@/article'
 #     sort: date desc                    # Sort by frontmatter field
 #
 # fetch: