uniweb 0.60.0 → 0.62.0

package/src/utils/foundation-name.js

@@ -0,0 +1,179 @@
+/**
+ * Giving a foundation its name — `name` in `main.js`'s default export.
+ *
+ * The rule itself (main.js `name`, else package.json `name`; `src` and `foundation`
+ * refused) is `@uniweb/build`'s `foundation-name.js`, shared by the build, `register`
+ * and `push`. This module only WRITES the name: the scaffold at `create` / `add`, and
+ * `register` when it asks for one.
+ *
+ * ⛔ NO `@uniweb/build` IMPORT, AND NO IMPORT OF main.js. `uniweb create` runs before
+ * any project exists: `@uniweb/build` is an optional peer that may not be installed,
+ * and main.js's own imports may not be either. Hence text scans rather than a load,
+ * and the one duplicated fact below, pinned to the build's list by
+ * `test/foundation-name.test.js`. What a foundation IS named is always read by the
+ * build (`readFoundationName`); these only decide where to write.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+
+// The folders a foundation's code lives in — never a foundation's name
+// (`@uniweb/build`'s FORBIDDEN_FOUNDATION_NAMES; the test keeps them equal).
+export const SCAFFOLD_FOLDER_NAMES = new Set(['src', 'foundation'])
+
+// Written above the name wherever the CLI adds one — the scaffold's main.js
+// template says the same.
+const NAME_COMMENT = '// What this foundation registers as — @<org>/<name> — and what sites pin.'
+
+/**
+ * A name made from free text — a project's name, a folder's — in the form a
+ * foundation name takes: lowercase letters, digits and inner hyphens.
+ * `My Site` → `my-site`. Null when nothing usable is left, or when what is left
+ * names a folder rather than a foundation.
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function normalizeFoundationName(raw) {
+  const name = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@[^/]*\//, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return name && !SCAFFOLD_FOLDER_NAMES.has(name) ? name : null
+}
+
+/**
+ * A name to offer a foundation that has none of its own: its folder's — or, for
+ * the `src/` and `foundation/` a scaffold makes, its project's folder. Null when
+ * neither makes one.
+ *
+ * @param {string} foundationDir
+ * @returns {string|null}
+ */
+export function suggestFoundationName(foundationDir) {
+  const dir = resolve(foundationDir)
+  return (
+    normalizeFoundationName(basename(dir)) ||
+    normalizeFoundationName(basename(dirname(dir)))
+  )
+}
+
+/**
+ * Whether `main.js`'s default export names the foundation — a `name` key at the
+ * export's own level, not one nested in `props` or `vars`.
+ *
+ * A scan, not a parse (see the module note): it skips strings and comments and
+ * counts brackets, which is all an object literal of declarations needs. A name
+ * that arrives by a spread is invisible to it — the build's read is the truth.
+ *
+ * @param {string} text - main.js source
+ * @returns {boolean}
+ */
+export function mainNamesFoundation(text) {
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) return false
+  let depth = 1
+  let atKey = true // just after the opening brace, or a comma at the top level
+  for (let i = opening.index + opening[0].length; i < text.length && depth > 0; i++) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      i = text.indexOf('\n', i)
+      if (i < 0) break
+    } else if (c === '/' && text[i + 1] === '*') {
+      i = text.indexOf('*/', i + 2) + 1
+      if (i <= 0) break
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1
+      while (j < text.length && text[j] !== c) j += text[j] === '\\' ? 2 : 1
+      if (depth === 1 && atKey && text.slice(i + 1, j) === 'name' && /^\s*:/.test(text.slice(j + 1))) {
+        return true
+      }
+      i = j
+      atKey = false
+    } else if ('{[('.includes(c)) {
+      depth++
+      atKey = false
+    } else if ('}])'.includes(c)) {
+      depth--
+    } else if (depth === 1 && c === ',') {
+      atKey = true
+    } else if (depth === 1 && atKey && /[A-Za-z_$]/.test(c)) {
+      const word = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))[0]
+      // `name: 'x'`, or the shorthand `{ name }`
+      if (word === 'name' && /^\s*[:,}]/.test(text.slice(i + word.length))) return true
+      i += word.length - 1
+      atKey = false
+    } else if (!/\s/.test(c)) {
+      atKey = false
+    }
+  }
+  return false
+}
+
+/**
+ * Write `name` into a foundation's `main.js`.
+ *
+ * With `replace`, the one `name: '<replace>'` literal is rewritten — the case where
+ * main.js already names the foundation, with a name that cannot register. Without
+ * it, `name` becomes the default export's first key. A missing main.js is created.
+ *
+ * ⚠️ A text edit, not a parse: it handles `export default { … }` — every scaffold
+ * and every template — and says so otherwise rather than guessing.
+ *
+ * @param {string} mainFile
+ * @param {string} name - already a valid foundation name
+ * @param {{ replace?: string|null }} [opts]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function writeFoundationName(mainFile, name, { replace = null } = {}) {
+  const line = `${NAME_COMMENT}\n  name: '${name}',`
+  if (!existsSync(mainFile)) {
+    writeFileSync(mainFile, `export default {\n  ${line}\n}\n`)
+    return { ok: true }
+  }
+  const text = readFileSync(mainFile, 'utf8')
+
+  if (replace !== null) {
+    const literal = new RegExp(
+      `(\\bname\\s*:\\s*)(['"\`])${replace.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\2`,
+      'g'
+    )
+    const hits = text.match(literal) || []
+    if (hits.length !== 1) {
+      return {
+        ok: false,
+        reason: `main.js does not name the foundation "${replace}" in exactly one place`
+      }
+    }
+    writeFileSync(mainFile, text.replace(literal, `$1'${name}'`))
+    return { ok: true }
+  }
+
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) {
+    return { ok: false, reason: 'main.js has no `export default { … }` to add a name to' }
+  }
+  // The name leads the export — on lines of its own, so a multi-line export keeps
+  // its first line and gains a blank one between.
+  const at = opening.index + opening[0].length
+  writeFileSync(mainFile, `${text.slice(0, at)}\n  ${line}\n${text.slice(at)}`)
+  return { ok: true }
+}
+
+/**
+ * Give a freshly scaffolded foundation its name, unless its main.js already has one.
+ *
+ * Called after template content is applied, because a template's own main.js
+ * replaces the scaffolded one — and with it the name the scaffold wrote.
+ *
+ * @param {string} foundationDir - the scaffolded package (flat layout: main.js at its root)
+ * @param {string|null} name
+ */
+export function ensureFoundationName(foundationDir, name) {
+  if (!name) return
+  const mainFile = join(foundationDir, 'main.js')
+  if (existsSync(mainFile) && mainNamesFoundation(readFileSync(mainFile, 'utf8'))) return
+  writeFoundationName(mainFile, name)
+}

package/src/utils/git.js

@@ -37,12 +37,15 @@ export function siteContentRoots(siteDir) {
   // root added below already covered it and the bare `'collections.yml'` entry
   // that used to sit in this list resolved to a path no site ever had. A
   // root-level file has no directory entry standing in for it.
+  //
+  // The records folder's `folder.yml` is the reverse case: it lives in the records
+  // directory, which is a root below, so it needs no entry. (It was `records.yml` at
+  // the site root until 2026-09-21, and was listed here then.)
   const roots = new Set([
     'site.yml',
     'theme.yml',
     'head.html',
     'queries.yml',
-    'records.yml',
     'locales'
   ])
   let paths = {}
@@ -54,7 +57,7 @@ export function siteContentRoots(siteDir) {
   }
   roots.add(paths.pages || 'pages')
   roots.add(paths.layout || 'layout')
-  roots.add(paths.entities || 'entities')
+  roots.add(paths.records || 'records')
   return [...roots]
 }
 

package/src/utils/records-guard.js

@@ -1,42 +1,47 @@
 // ⛔ 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.
+// A push sends the site's records folder whole, and it REPLACES the backend's. A site
+// with no records directory sends none and leaves the backend's alone; a records
+// directory that holds no records sends an EMPTY folder, and the backend removes what
+// is there. The asymmetry is well-shaped — the safe state is the ABSENCE of the
+// directory, so a site whose records live only on the backend is never emptied by a
+// push of its pages — and it leaves exactly one sharp edge: a directory emptied by
+// accident, or kept with only a placeholder (`records/.gitkeep`), and pushed.
 //
-// ⚠️ 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 CLI DOES THE ASKING. Never make "empty" mean "missing" to dodge this: that
+// would delete a capability to avoid writing a prompt.
 //
-// ⭐ 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.
+// ⛔ Until 2026-09-21 both states were `records.yml`'s — missing and empty — because
+// that file listed the records. The directory holds them now (`@uniweb/build`'s
+// `sendsFolder` decides what a push sends, and this asks about exactly its empty case).
 //
 // 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 { readEntityPool } 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.
+ * Record placements in a banked placement 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.
+ * ⭐ A placement banked since 2026-09-21 is keyed by the record it references —
+ * `@<record uuid>`, one per record — so where those exist they ARE the count. A map
+ * banked before holds `name` chains only: 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 — or, with both kinds of key, each record twice.
  */
 export function countPlacedRecords(pathToUuid) {
-  const paths = Object.keys(pathToUuid || {})
-  return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(`${p}/`))).length
+  const keys = Object.keys(pathToUuid || {})
+  const byRecord = keys.filter((k) => k.startsWith('@'))
+  if (byRecord.length) return byRecord.length
+  return keys.filter((p) => !keys.some((q) => q !== p && q.startsWith(`${p}/`))).length
 }
 
 /**
- * Stop an empty `records.yml` from silently emptying a live folder.
+ * Stop an empty records directory from silently emptying the backend's folder.
  *
  * @param {object} params
  * @param {string} params.siteDir
@@ -48,8 +53,10 @@ export function countPlacedRecords(pathToUuid) {
  * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
  */
 export async function guardEmptyRecords({ siteDir, backend, args = [], warn, note }) {
-  const cfg = await readRecordsConfig(siteDir)
-  if (cfg.state !== FOLDER_EMPTY) return { ok: true, count: 0 }
+  const pool = await readEntityPool(siteDir)
+  // Only a directory that is there and holds nothing at all — no records, and no
+  // files that fail to be records — sends the empty folder.
+  if (!pool.exists || pool.entities.length > 0 || pool.errors.length > 0) return { ok: true, count: 0 }
 
   const count = countPlacedRecords(readFolderItemUuids(siteDir, backend))
   // Nothing banked ⇒ nothing this push can remove. A first push of an empty
@@ -58,13 +65,13 @@ export async function guardEmptyRecords({ siteDir, backend, args = [], warn, not
   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.`
+    `${pool.dir}/ holds no records, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the site's folder on the backend.`
   )
   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.'
+    `An empty ${pool.dir}/ means "the folder holds nothing" — it is not the same as having no ` +
+      `${pool.dir}/ at all, which leaves the backend's folder alone. If you did not mean to remove ` +
+      `them, put the files back (or pull) before pushing.`
   )
 
   // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
@@ -76,6 +83,6 @@ export async function guardEmptyRecords({ siteDir, backend, args = [], warn, not
     return { ok: false, count }
   }
 
-  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the live folder?`, false)
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the site's folder?`, false)
   return { ok: yes, count }
 }

package/src/utils/registry-orgs.js

@@ -59,6 +59,25 @@ export function bareHandle(scope) {
     .replace(/\/.*$/, '')
 }
 
+/**
+ * A publish scope in the one form the registry names things by — `@acme` — from any
+ * spelling `--scope` or `package.json::uniweb.scope` may carry it in (`@acme`, `acme`,
+ * `@acme/…`). Null when there is no handle in it.
+ *
+ * ⛔ Every name built from a scope goes through this. The `.uwx` assembly
+ * (`@uniweb/build`'s `buildRegistryPackage`) has always accepted `acme` as well as
+ * `@acme`, so a name composed from the RAW value disagreed with the one it registered:
+ * until 2026-09-21 `register --scope std` registered `@std/src` and then asked to
+ * deliver code for `std/src`, which the registry refuses (a scoped name is `@org/name`).
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function publishScope(value) {
+  const handle = bareHandle(value)
+  return handle ? `@${handle}` : null
+}
+
 /**
  * Validate a handle's GRAMMAR client-side (reserved names are the server's
  * call — a 409 carries the verdict). Returns an error string, or null.

package/src/utils/scaffold.js

@@ -76,14 +76,16 @@ export async function getWorkspaceTemplateOutputs({ blank = false } = {}) {
 }
 
 /**
- * Scaffold a foundation from the foundation package template
+ * Scaffold a foundation from the foundation package template.
  *
- * @param {string} targetDir - Target directory for the foundation
+ * @param {string} targetDir
  * @param {Object} context - Template context
- * @param {string} context.name - Package name
+ * @param {string} context.name - Package name — workspace plumbing (`src`, `docs-src`)
+ * @param {string} [context.registryName] - The foundation's own name, written to
+ *   main.js's `name`: what it registers as (`@org/<name>`). Omitted when none can be
+ *   made, and `uniweb register` asks for one
  * @param {string} context.projectName - Workspace name
- * @param {boolean} [context.isExtension] - Whether this is an extension
- * @param {Object} [options] - Processing options
+ * @param {boolean} [context.isExtension]
  */
 export async function scaffoldFoundation(targetDir, context, options = {}) {
   registerVersions(getVersionsForTemplates())

package/starter/foundation/main.js

@@ -6,7 +6,8 @@
  * - defaultLayout: Name of the default layout from src/layouts/ (optional)
  * - props: Foundation-wide props accessible via website.foundationProps
  *
- * Identity (name, version, description) comes from package.json.
+ * Name: `name` in the default export is what this foundation registers as
+ * (@org/<name>) — `uniweb create` adds it. The version comes from package.json.
  */
 
 // Create a layout at src/layouts/MyLayout/index.jsx

package/templates/foundation/main.js.hbs

@@ -14,10 +14,19 @@
 
 {{#if isExtension}}
 export default {
+{{#if registryName}}
+  name: '{{registryName}}',
+{{/if}}
   extension: true,
 }
 {{else}}
 export default {
+{{#if registryName}}
+  // ─── Name ───────────────────────────────────────────────────────────────────
+  // What this foundation registers as — @<org>/<name> — and what sites pin.
+  name: '{{registryName}}',
+
+{{/if}}
   // ─── Layout ─────────────────────────────────────────────────────────────────
   // Create layouts in layouts/MyLayout/index.jsx (auto-discovered).
   // defaultLayout: 'MyLayout',

package/templates/site/site.yml.hbs

@@ -25,7 +25,7 @@ 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
-#   entities: ./data                # Where this site's entities live
+#   records: ./data                 # Where this site's records 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
@@ -41,14 +41,17 @@ index: home
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose:
 #
-#   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
+#   records/{schema}/    your site's records — every file here is one. The folder
+#                        names their data schema:
+#                          records/article/        → @/article  (your foundation's)
+#                          records/std/person/     → @std/person
+#                        A file whose name starts with `_` is not a record.
+#   records/folder.yml   OPTIONAL — sorts records into folders a query can slice
+#                        with `scope:`. The one file in records/ that is not a
+#                        record. Most sites have none:
+#                            - folder: archive
+#                              records:
+#                                - article/2025-*.md
 #   queries.yml          HOW CONTENT IS REACHED — named queries over those records:
 #                            recent:
 #                              schema: '@/article'