@uniweb/projections 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/projections",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Projections of a Uniweb site's content — agent index, per-page markdown, search index. Pure JS, runs anywhere.",
   "type": "module",
   "exports": {
@@ -31,8 +31,8 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/content-writer": "^0.3.3",
-    "@uniweb/core": "^0.8.5"
+    "@uniweb/core": "^0.9.0",
+    "@uniweb/content-writer": "^0.3.3"
   },
   "devDependencies": {
     "vitest": "^4.1.7",

package/src/config.js

@@ -21,6 +21,29 @@ const DEFAULTS = {
   branchMinPages: DEFAULT_BRANCH_MIN_PAGES,
 }
 
+/**
+ * Every key the `agents:` block accepts — the author-facing vocabulary.
+ *
+ * ⚠️ **This is deliberately WIDER than what {@link resolveAgentsConfig} reads.**
+ * Some keys are *carried* rather than honoured: the framework passes them
+ * through to the host, which enforces them, and this package never looks at
+ * them. `expectedOrigins` is the first — the host checks the `Origin` of
+ * requests to its agent endpoint against it.
+ *
+ * ⛔ **A carry-only key still has to be listed here, and the reason is the whole
+ * point of the list.** The block reaches a backend as opaque JSON, so nothing
+ * downstream can reject a typo — an author who writes `expectedOrgins` gets a
+ * site that looks configured and checks nothing, silently, forever. The only
+ * lane that can catch it is the one that owns the words. `uniweb doctor` reads
+ * this list; if you add a key to the block and not to this list, doctor will
+ * call the author's correct spelling a typo.
+ */
+export const AGENTS_KEYS = Object.freeze([
+  ...Object.keys(DEFAULTS),
+  // Carried, not honoured here — see the note above before removing.
+  'expectedOrigins',
+])
+
 /**
  * Read the site's `agents:` block.
  *

package/src/index.js

@@ -37,6 +37,7 @@ export {
 export {
   INDEX_FILENAME,
   DEFAULT_BRANCH_MIN_PAGES,
+  AGENTS_KEYS,
   pageMarkdownFilename,
   branchIndexFilename,
   resolveAgentsConfig,

package/src/pages.js

@@ -109,13 +109,24 @@ export function isKnowledgeRoute(route, roots) {
  *   rendered and cannot be reached by a visitor, so nothing describing the
  *   *public* site may name it.
  *
- * ⛔ That last one is a disclosure boundary, not a tidy-up, and the mistake it
- * corrects was invisible for a reason worth stating. These projections are the
- * **free** tier; the agent corpus that knowledge pages exist for is the
- * **paid** one. Leaving `knowledge` out of this list did not merely list a
- * page — it published the body an author wrote for a capability they may never
- * have bought, at `llms.txt`, at `/{route}.md`, and in the search index. It
- * also made {@link selectCorpusPages} degenerate: that selector is *public ∪
+ * ⛔ **That last one is about who the prose is ADDRESSED to — it is not a
+ * confidentiality boundary, and reading it as one produces wrong designs.**
+ * A knowledge page is source material for a service the site runs for its
+ * visitors; the explanations in it are written for that service to reason
+ * with, not for a person or a crawler to read. So naming it in `llms.txt`,
+ * `/{route}.md` or the search index is not "exposing a secret" — it is
+ * serving a reader prose that was written for somebody else, in a file that
+ * claims to describe the public site.
+ *
+ * ⚠️ **Do not build a security expectation on this.** The service can quote
+ * its source material back to whoever prompts it — that is what it is for —
+ * so knowledge content is reachable by a visitor through the service by
+ * design. [Diego, 2026-08-13]: *"It is not the case that it's private in the
+ * sense of sensitive. It is given to the agent so they can reason and respond
+ * prompts."*
+ *
+ * The omission still mattered, just not for the reason first written here: it
+ * also made {@link selectCorpusPages} degenerate. That selector is *public ∪
  * knowledge*, and while knowledge rode in the public half the union added
  * nothing and read as if it worked.
  *

package/src/search/collections.js

@@ -6,26 +6,57 @@
  * per-record detail files into each item before calling this function.
  */
 
+/**
+ * Compose a record's route the way the build does, for the sources that have
+ * not already done it.
+ *
+ * `collections[name].route` is authored in `site.yml` (see the blog and
+ * international templates). When it is set, the build's collection processor
+ * already stamps `item.route` on every record — so the route below is a
+ * *fallback* for records that arrived without one (an API-backed collection a
+ * host assembled itself), never a second opinion about records that have one.
+ *
+ * The trailing-slash strip matches `collectItems` in
+ * `@uniweb/build`'s `site/collection-processor.js`. Without it a `route:
+ * /blog/` authored with a slash yields `/blog//my-post` here and
+ * `/blog/my-post` there — two answers to one question, on a value nobody
+ * checks until a visitor clicks it.
+ */
+function composeRoute(configRoute, slug) {
+  if (typeof configRoute !== 'string' || configRoute === '') return undefined
+  return `${configRoute.replace(/\/$/, '')}/${slug}`
+}
+
 /**
  * @param {string} name - Collection name (e.g. "articles")
  * @param {Object} config - Collection config from site.yml (config.collections[name])
- * @param {Object} collectionData - Parsed cascade JSON (`data/{name}.json`)
+ * @param {Object[]|Object} collectionData - Parsed cascade JSON (`data/{name}.json`),
+ *   which the build writes as a bare array. The `{ items: [...] }` envelope is
+ *   accepted too, since a host fetching the collection from a backend may carry one.
  * @param {string} locale - Locale code (e.g. "en")
  * @returns {Object} Collection search index
  */
 export function generateCollectionIndex(name, config, collectionData, locale) {
   const fields = config.search?.fields || ['title']
   const weight = config.search?.weight ?? 0.7
-  const items = collectionData?.items || []
+  const items = Array.isArray(collectionData)
+    ? collectionData
+    : collectionData?.items || []
 
   const entries = items.map(item => {
     const content = fields.map(f => item[f] || '').filter(Boolean).join(' ')
     const slug = item.slug || item.id || String(item.title || '').toLowerCase().replace(/\s+/g, '-')
+    // The record's own route wins: the build already resolved it against the
+    // same config, so recomputing here could only disagree. `route` is omitted
+    // entirely when neither source can supply one — a missing key is detectable
+    // by a consumer, where the string "undefined/my-post" is a link that ranks
+    // correctly, looks plausible, and 404s on click.
+    const route = item.route || composeRoute(config.route, slug)
     return {
       id: `collection:${name}:${slug}`,
       type: 'collection',
       collection: name,
-      route: `${config.route}/${slug}`,
+      ...(route ? { route } : {}),
       title: item.title || item.name || slug,
       content,
       excerpt: content.length > 160