@uniweb/build 0.77.0 → 0.79.0

package/src/site/query-processor.js

@@ -51,7 +51,7 @@
  * await writeQueryFiles(siteDir, byQuery)
  */
 
-import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
+import { readFile, readdir, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
 import { join, basename, extname, dirname, relative, resolve, sep, isAbsolute } from 'node:path'
 import { existsSync } from 'node:fs'
 import { createHash } from 'node:crypto'
@@ -59,7 +59,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
 import { DATA_DIR, withoutRouteVariables, mapQueryPaths, BRANCH_KEY } from '@uniweb/core'
-import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
+import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
@@ -126,7 +126,6 @@ function parseQueryConfig(name, config) {
       scope: null,
       sort: null,
       where: null,
-      filter: null,
       limit: 0,
       excerpt: { maxLength: 160 },
     }
@@ -136,6 +135,7 @@ function parseQueryConfig(name, config) {
   refuseOutsideLanguage(config.where, `queries.${name}`)
   refuseQueryRoute(config, `queries.${name}`)
   refuseLimit(config.limit, `queries.${name}`)
+  refuseFilter(config, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records — `records/{schema}/` declares the
@@ -146,11 +146,8 @@ function parseQueryConfig(name, config) {
     // here until 2026-09-11: a named query's `scope` was ignored on this lane.
     scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
-    // `where:` is the CANONICAL predicate; `filter:` is the deprecated string DSL
-    // it replaced. Both are carried and both are applied below, in the same order
-    // `data-fetcher.js::applyPostProcessing` uses — see the note there.
+    // The predicate. ⛔ `filter:`, the string DSL it replaced, is refused above.
     where: config.where || null,
-    filter: config.filter || null,
     limit: config.limit || 0,
     excerpt: {
       maxLength: config.excerpt?.maxLength || 160,
@@ -1379,8 +1376,8 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
 
     // ⭐ TWO PAYLOADS FOR EVERY QUERY (ruled 2026-09-27 [Diego]):
     //   1. Each record WHOLE, as stored, at /data/<name>/<$name>.json — a key per section, the
-    //      brief's included — what a whole question answers: a parametric page's record for a
-    //      component that declares `'@x/y/*'`, and kit's `useWholeRecord`.
+    //      brief's included — what a whole question answers: a record for a component that
+    //      declares its key `whole: true`, and kit's `useWholeRecord`.
     //   2. The list at /data/<name>.json — each record's BRIEF, the brief's fields at the top —
     //      what `query: <name>` delivers everywhere else. ⛔ `deferred:`, which left fields of the
     //      brief out of it, was retired the same day [Diego].
@@ -1419,36 +1416,3 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
     }
   }
 }
-
-/**
- * Get last modified time for a collection
- *
- * @param {string} siteDir - Site root directory
- * @param {Object} config - Collection config
- * @returns {Promise<Date|null>} Most recent modification time
- */
-export async function getQueryLastModified(siteDir, config) {
-  const parsed = parseQueryConfig('temp', config)
-  const poolDir = join(siteDir, parsed.path)
-
-  if (!existsSync(poolDir)) {
-    return null
-  }
-
-  const files = await readdir(poolDir)
-  const itemFiles = files.filter(f =>
-    !f.startsWith('_') &&
-    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json') || f.endsWith('.bib'))
-  )
-
-  let lastModified = null
-
-  for (const file of itemFiles) {
-    const fileStat = await stat(join(poolDir, file))
-    if (!lastModified || fileStat.mtime > lastModified) {
-      lastModified = fileStat.mtime
-    }
-  }
-
-  return lastModified
-}

package/src/uwx/emit-surface.json

@@ -45,9 +45,6 @@
         "agents": [
           "site.yml::agents"
         ],
-        "assistant": [
-          "site.yml::assistant"
-        ],
         "base": [
           "site.yml::base"
         ],
@@ -89,19 +86,10 @@
         "publish_languages": [
           "site.yml::publishLanguages"
         ],
-        "search": [
-          "site.yml::search"
-        ],
         "seo": [
           "site.yml::seo"
         ],
-        "submit": [
-          "site.yml::submit"
-        ],
-        "theme": null,
-        "tracking": [
-          "site.yml::tracking"
-        ]
+        "theme": null
       }
     },
     "services": {

package/src/uwx/index.js

@@ -12,6 +12,8 @@
 
 export { mintUuidV7 } from './uuid.js'
 export { createZip, readZip } from './zip.js'
+// The queries whose records a site's pages show live — what `records` is for.
+export { recordQueriesShown } from './shown-records.js'
 export {
   sha256Hex,
   toJsonBuffer,
@@ -52,7 +54,8 @@ export {
   queriesYmlPath,
   QUERIES_YML_RELPATH,
 } from './queries-config.js'
-export { upsertYamlScalar, removeYamlScalar } from './yaml-upsert.js'
+// Edits to a YAML file an author wrote — the one editor; files are written through project-writer.js.
+export { editYamlText, setYamlKey, replaceInYamlList } from './yaml-edit.js'
 export { buildFolderEntity,
   collectFolderItemUuids,
   stampFolderItemUuids
@@ -116,11 +119,14 @@ export {
 // A site's services request — `site.yml::services`, applied over the site's own rows.
 // Spec: kb/framework/reference/site-services-request.md
 export {
+  RUNTIME_KEYS,
   readServicesRequest,
-  takeServices,
-  mergeServiceRows,
-  reconcileServices,
-  recordAfter,
+  unreadableServices,
+  refuseUnreadableServices,
+  statedServices,
+  heldServices,
+  servicesFromDocument,
+  sameServiceRow,
 } from './services-request.js'
 export {
   diffSiteUnits,
@@ -130,6 +136,7 @@ export {
   walkSiteUnits,
   collectUnitUuids,
   collectQueryUuids,
+  siteItemsByKey,
   stampUnitUuids,
 } from './site-diff.js'
 export {

package/src/uwx/project-writer.js

@@ -22,6 +22,7 @@ import { canonicalJson, sameMarkdownDocument } from './same-content.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
 import { folderYmlPath } from '../site/records-config.js'
+import { editYamlText, YAML_DUMP_OPTS } from './yaml-edit.js'
 import { DECLARATION_KEYS } from '../site/fetch-shapes.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
@@ -45,9 +46,6 @@ export const DEFAULT_RESERVED_FRONTMATTER = new Set([
   // editor toggles it, so a pull must carry the store's value into the file (2026-09-28).
 ])
 
-// js-yaml dump options shared by every config write, so output is byte-stable.
-export const YAML_DUMP_OPTS = { lineWidth: -1, quotingType: "'", forceQuotes: false, noRefs: true }
-
 /**
  * Write `text` to `filePath` only when it differs from what's on disk, using a
  * tmp-file + rename so a reader never sees a half-written file. Creates the
@@ -216,10 +214,8 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
 // Shallow-merge `changes` into a YAML config file and write idempotently. A key
 // whose value is null/undefined is deleted; an object value is shallow-merged one
 // level deep (so partial `theme` / `build` updates don't drop sibling keys) unless
-// the key is in `replace`; any other value replaces. NOTE: this re-dumps the file,
-// so author comments/order are not preserved — acceptable for machine-owned
-// config, but comment-preserving merges for hand-authored config files are a
-// quality bar to revisit.
+// the key is in `replace`; any other value replaces. The file is edited, not
+// re-dumped: its comments and layout stay (`writeYamlIfChanged`).
 function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   const prior = loadYamlFile(filePath)
   const existing = isPlainObject(prior.value) ? { ...prior.value } : {}
@@ -240,23 +236,37 @@ function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   return writeYamlIfChanged(filePath, existing, prior)
 }
 
-// A YAML file, parsed — and whether there was one: a missing or unreadable file is never "unchanged".
+// A YAML file, parsed, with its text — and whether there was one: a missing file is never "unchanged".
+// ⛔ One that EXISTS and does not parse is refused, never read as missing: read as missing, the writer
+// replaced the author's whole file with only the keys it was writing (until 2026-10-07).
 function loadYamlFile(filePath) {
+  let text
   try {
-    return { value: yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) ?? {}, read: true }
+    text = readFileSync(filePath, 'utf8')
   } catch {
-    return { value: {}, read: false }
+    return { value: {}, read: false, text: null }
+  }
+  try {
+    return { value: yaml.load(text, YAML_OPTIONS) ?? {}, read: true, text }
+  } catch (err) {
+    throw new Error(`${filePath} is not YAML that can be read, so it was not written: ${err.message.split('\n')[0]}`)
   }
 }
 
-// ⭐ A FILE WHOSE MEANING WOULD NOT CHANGE IS LEFT AS ITS AUTHOR WROTE IT. Every writer here re-dumps the
-// whole file — its comments dropped, its strings re-quoted, its lists reflowed — so a pull that restated
-// a file rewrote it all the same. ⛔ Until 2026-09-26 a pull into the copy that pushed it re-dumped
-// `site.yml`, `theme.yml` and every `page.yml` (measured on the `international` template: every comment
-// in its `site.yml` gone, and nothing had changed).
+// ⭐ A FILE WHOSE MEANING WOULD NOT CHANGE IS LEFT AS ITS AUTHOR WROTE IT. ⛔ Until 2026-09-26 a pull into
+// the copy that pushed it re-dumped `site.yml`, `theme.yml` and every `page.yml` (measured on the
+// `international` template: every comment in its `site.yml` gone, and nothing had changed).
+//
+// ⭐ AND ONE THAT CHANGES IS EDITED, NOT RE-DUMPED (2026-10-07): only the entries that differ are
+// rewritten, and every comment, blank line and list the author wrote stays (`editYamlText`). ⛔ Until then
+// every writer here dumped the whole file — a pull that changed one key of `site.yml` left the Starter
+// template's 93 lines as 10, and a `pull --merge` conflicted on the whole commented header. The whole dump
+// remains for a file with nothing to keep (none yet, unreadable) and one the editor declines (an alias or a
+// `<<` merge key, or a result that would read differently).
 function writeYamlIfChanged(filePath, value, prior) {
   if (prior.read && canonicalJson(value) === canonicalJson(prior.value)) return 'unchanged'
-  return writeIfChanged(filePath, yaml.dump(value, YAML_DUMP_OPTS))
+  const edited = prior.read ? editYamlText(prior.text, prior.value, value, YAML_DUMP_OPTS) : null
+  return writeIfChanged(filePath, edited ?? yaml.dump(value, YAML_DUMP_OPTS))
 }
 
 const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
@@ -280,10 +290,10 @@ export function writeSiteConfig(siteRoot, config) {
 const SITE_CONFIG_WHOLE = Object.freeze([...DECLARATION_KEYS, 'services'])
 
 /**
- * Write a YAML object to a file (full dump, idempotent) — for machine-owned
+ * Write a YAML object to a file (idempotent) — for machine-owned
  * config the projector authors wholesale, e.g. a projected `page.yml`/`folder.yml`.
- * (Comment/unknown-key preservation is a later refinement; `site.yml`/
- * `collections.yml` use the merging writers instead.)
+ * An existing file is edited, not re-dumped — its comments stay (`writeYamlIfChanged`);
+ * `site.yml` and `queries.yml` use the merging writers.
  * @returns {'updated'|'unchanged'}
  */
 export function writeYamlFile(filePath, obj) {
@@ -296,7 +306,7 @@ export function writeYamlFile(filePath, obj) {
  * absent from `projected` is removed (the projector owns the managed set
  * wholesale); unknown keys keep their value and relative order. Idempotent.
  *
- * Same key-preserving (comment-dropping) bar as `writeSiteConfig` — for the
+ * Same key- and comment-preserving bar as `writeSiteConfig` — for the
  * hand-authored `page.yml`/`folder.yml`, whose author-added keys must survive a
  * pull rather than being clobbered by a full re-dump.
  *
@@ -323,7 +333,7 @@ export function writeMergedYaml(filePath, projected, managedKeys) {
 /**
  * Merge `queries` into `queries.yml` (shallow). Preserves queries not in the
  * incoming set; each incoming one is replaced wholesale. Same key-preserving
- * (comment-dropping) bar as `writeSiteConfig`.
+ * (and comment-preserving) bar as `writeSiteConfig`.
  *
  * ⛔ `queries.yml` IS THE MAP — there is no root key, so `queries` is passed bare.
  * The predecessor wrote `{ collections: {...} }` into `collections.yml`; handing