@uniweb/unipress 0.8.11 → 0.8.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
   "type": "module",
   "publishConfig": {
@@ -49,11 +49,11 @@
     "prompts": "^2.4.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@uniweb/content-reader": "^1.2.3",
-    "@uniweb/runtime": "^0.12.6",
-    "@uniweb/semantic-parser": "^1.2.3",
-    "@uniweb/build": "^0.25.0",
-    "@uniweb/core": "^0.11.0"
+    "@uniweb/runtime": "^0.12.10",
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/build": "^0.26.0",
+    "@uniweb/core": "^0.12.0",
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "devDependencies": {
     "vitest": "^4.1.7"

package/src/foundation-loader.js

@@ -33,6 +33,7 @@ import { resolve, isAbsolute, join, dirname } from 'node:path'
 import { FoundationResolutionError } from './errors.js'
 import { findCatalogEntry } from './catalog.js'
 import { fetchFoundationToCache } from './foundation-fetch.js'
+import { foundationUrl } from './registry-base.js'
 
 const URL_PATTERN = /^https?:\/\//
 const PATH_PATTERN = /^(\.\.?[\/\\]|[\/\\]|[A-Za-z]:[\/\\])/
@@ -42,32 +43,15 @@ const PATH_PATTERN = /^(\.\.?[\/\\]|[\/\\]|[A-Za-z]:[\/\\])/
 // registry decides what's valid.
 const REGISTRY_REF_PATTERN = /^@([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)@([0-9a-z][0-9a-z.\-+]*)$/i
 
-// unipress's bundled foundations are distributed as static artifacts on
-// the unipress repo's GitHub Pages site. URL pattern:
-//
-//   https://uniweb.github.io/unipress/foundations/<name>/<version>/entry.js
-//
-// The namespace portion of a registry ref is implicit — every foundation
-// served from this base is under @uniweb/. Set UNIWEB_REGISTRY_URL to
-// override (e.g., for testing against a local http.server during foundation
-// development, or for users with a private alternative).
-const DEFAULT_REGISTRY_BASE = 'https://uniweb.github.io/unipress'
 const DEFAULT_BUILT_ENTRY = 'dist/entry.js'
 
-function getRegistryBase() {
-  const raw = process.env.UNIWEB_REGISTRY_URL || DEFAULT_REGISTRY_BASE
-  return raw.replace(/\/$/, '')
-}
-
-// Build the URL for a registry ref. The namespace is preserved in the
-// returned URL only when the base wants it; for the GH Pages distribution
-// the namespace is implicit and the path is <base>/foundations/<name>/<ver>/.
-// If a custom UNIWEB_REGISTRY_URL needs the namespace in the path, it can
-// hold a path prefix that resolves accordingly (e.g., set
-// `UNIWEB_REGISTRY_URL=https://my.host/by-ns/uniweb` and live without the
-// per-namespace split, or maintain a redirect rule on that host).
+// Build the URL for a registry ref. The base + layout live in registry-base.js,
+// shared with the catalog so the URL we FETCH and the URL we SHOW cannot drift
+// (and so both honour UNIWEB_REGISTRY_URL). The `namespace` is accepted and
+// unused: every foundation under this layout is @uniweb/, so a ref's scope does
+// not appear in the path — see foundationPath's note on per-namespace bases.
 function buildRegistryUrl(namespace, name, version) {
-  return `${getRegistryBase()}/foundations/${name}/${version}/entry.js`
+  return foundationUrl(name, version)
 }
 
 export async function resolveFoundationRef(ref, { anchorDir, onProgress = () => {} } = {}) {

package/src/foundations-data.js

@@ -14,9 +14,9 @@
  * ─────────────────────────────────────────────────────────────────────────
  *
  * Foundations are deployed as static artifacts to the unipress repo's
- * GitHub Pages site. URL pattern:
- *
- *   https://uniweb.github.io/unipress/foundations/<name>/<version>/entry.js
+ * GitHub Pages site. **The base and the URL rule live in `registry-base.js`** —
+ * one definition, shared with `foundation-loader.js`, so what this catalog shows
+ * and what `compile` fetches cannot disagree.
  *
  * On every push to main, `.github/workflows/deploy-foundations.yml`
  * builds each `foundations/<name>/` and layers the resulting `dist/` into
@@ -52,9 +52,23 @@
  *
  * Each entry's `foundation.source.url` is the human-meaningful "where this
  * foundation lives" pointer shown in `list-templates` output and post-create
- * messages. It mirrors the URL the loader builds at compile time, but does
- * not itself drive resolution — the loader builds its own URL from
- * `foundation.ref` + the configured base.
+ * messages. It does not itself drive resolution — the loader builds its own URL
+ * from `foundation.ref` + the configured base.
+ *
+ * ⚠️ **It is built from the same helper the loader resolves through**
+ * (`registry-base.js::foundationUrl`), and that is load-bearing rather than tidy.
+ * Until 2026-08-22 this file held its own hardcoded base, so it ignored
+ * `UNIWEB_REGISTRY_URL`: pointing unipress at a local registry left
+ * `list-templates` printing the GitHub Pages URL — an address the tool was not
+ * using, reported at exactly the moment someone was debugging which address it
+ * used. "Display only" is not "free to be wrong."
+ *
+ * ⛔ There is also a live fallback that DOES resolve from this field:
+ * `foundation-loader.js::resolveCatalogRef` fetches `source.url` directly when an
+ * entry carries no registry-shaped `foundation.ref` (the v0.1 legacy shape). No
+ * current entry hits it — all 8 carry a ref — but an entry added without one
+ * would resolve through this URL. Sharing the helper means that path honours the
+ * override too, instead of silently pinning to our origin.
  *
  * ─────────────────────────────────────────────────────────────────────────
  * Storage format
@@ -62,14 +76,17 @@
  *
  * Stored as a plain JS module (not YAML) so `bun build --compile` can
  * inline it at bundle time. The compiled binary has no filesystem for
- * runtime reads.
+ * runtime reads. Its one import (`registry-base.js`) is a zero-import leaf, so
+ * the catalog stays inlinable; the base is still read from the environment at
+ * call time rather than frozen into the binary.
  */
 
-const PUBLIC_FOUNDATIONS_BASE = 'https://uniweb.github.io/unipress/foundations'
+import { foundationUrl } from './registry-base.js'
 
-function publicUrl(name, version) {
-  return `${PUBLIC_FOUNDATIONS_BASE}/${name}/${version}/entry.js`
-}
+// `foundationUrl` is the SAME helper foundation-loader.js resolves through, so
+// what we show here is what compile will fetch — including under a
+// UNIWEB_REGISTRY_URL override, which the old local constant ignored.
+const publicUrl = (name, version) => foundationUrl(name, version)
 
 const BOOK_FOUNDATION = {
   ref: '@uniweb/book@0.4.2',

package/src/registry-base.js

@@ -0,0 +1,91 @@
+/**
+ * The unipress foundation registry — its origin and its URL rule.
+ *
+ * ## Why this is a module and not two constants
+ *
+ * unipress's bundled foundations are static artifacts on the unipress repo's
+ * GitHub Pages site, laid out as:
+ *
+ *   <base>/foundations/<name>/<version>/entry.js
+ *
+ * That layout is **ours** — `.github/workflows/deploy-foundations.yml` writes it
+ * — so a default origin is the correct answer rather than a guessed one, and the
+ * filename rule is ours to name. But the base is overridable (`UNIWEB_REGISTRY_URL`),
+ * which makes this a **writer/reader pair**:
+ *
+ *   reader  foundation-loader.js   buildRegistryUrl() — what `compile` FETCHES
+ *   reader  foundations-data.js    each entry's `foundation.source.url` — what
+ *                                  `create` and `list-templates` SHOW the user
+ *
+ * Before 2026-08-22 those held two hardcoded spellings of one base, decomposed
+ * differently — `foundations-data.js` baked `/foundations` into its constant while
+ * the loader kept it out and appended it when building. So the two edits needed to
+ * move the base did not look alike, and nothing caught a half-finished move. Worse,
+ * only the loader honoured `UNIWEB_REGISTRY_URL`: point unipress at a local
+ * registry and `list-templates` still printed the GitHub Pages URL, which is not
+ * the URL `compile` would fetch. A tool that reports an address it is not using is
+ * a bad instrument, and diagnostics is exactly when the override is in play.
+ *
+ * Same treatment as `@uniweb/core/icon-corpus`, for the same reason: one helper,
+ * no second spelling.
+ *
+ * ## ⛔ Keep this a LEAF — zero imports
+ *
+ * The import graph runs `foundation-loader.js` → `catalog.js` → `foundations-data.js`,
+ * so the catalog cannot import the loader — that is a cycle, and it is why the
+ * constant was duplicated in the first place rather than through carelessness. A
+ * leaf both sides import is the only shape that works. Keeping it import-free also
+ * keeps `bun build --compile` able to inline the catalog (see foundations-data.js
+ * § Storage format).
+ *
+ * @module unipress/registry-base
+ */
+
+/**
+ * Where unipress publishes its own foundations.
+ *
+ * Not a fallback for a missing address — it is the address of OUR artifact, and it
+ * is what makes `unipress create --template book` work with nothing configured.
+ */
+export const DEFAULT_REGISTRY_BASE = 'https://uniweb.github.io/unipress'
+
+/**
+ * The configured registry base: `UNIWEB_REGISTRY_URL` when set, else ours.
+ *
+ * Read at call time, not frozen at import, so a caller that sets the variable
+ * programmatically before invoking a command still gets it.
+ *
+ * @returns {string} the base, without a trailing slash
+ */
+export function getRegistryBase() {
+  const raw = process.env.UNIWEB_REGISTRY_URL || DEFAULT_REGISTRY_BASE
+  return String(raw).replace(/\/+$/, '')
+}
+
+/**
+ * The registry path for one foundation, relative to any base serving it.
+ *
+ * ⚠️ The **namespace is implicit** — every foundation under this layout is
+ * `@uniweb/`, so a ref's scope does not appear in the path. A custom
+ * `UNIWEB_REGISTRY_URL` that needs a per-namespace split carries it in the base
+ * (e.g. `https://my.host/by-ns/uniweb`) or answers it with a redirect.
+ *
+ * @param {string} name - the foundation name, unscoped (e.g. 'book')
+ * @param {string} version
+ * @returns {string}
+ */
+export function foundationPath(name, version) {
+  return `foundations/${name}/${version}/entry.js`
+}
+
+/**
+ * The full URL for one foundation against a serving base.
+ *
+ * @param {string} name - the foundation name, unscoped
+ * @param {string} version
+ * @param {string} [base] - serving base; defaults to the configured one
+ * @returns {string}
+ */
+export function foundationUrl(name, version, base = getRegistryBase()) {
+  return `${String(base).replace(/\/+$/, '')}/${foundationPath(name, version)}`
+}