uniweb 0.12.7 → 0.12.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.7",
+  "version": "0.12.8",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -46,9 +46,9 @@
     "@uniweb/runtime": "0.8.11"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.13.4",
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/content-reader": "1.1.10"
+    "@uniweb/build": "0.13.5",
+    "@uniweb/content-reader": "1.1.10",
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -165,10 +165,15 @@ The `uniweb` block in `package.json` carries platform-specific configuration tha
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `id` | `uniweb publish` | (set on first publish via the prompt, or via `--name`) | The foundation's published id — the bare-name segment in `~handle/<id>` or `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. |
+| `id` | `uniweb publish` | (set via `--name` or scoped `package.json::name`) | The foundation's published id — the bare-name segment in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. Only relevant for catalog-published foundations; site-bound foundations skip this. |
 | `namespace` | `uniweb publish` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
 | `runtimePolicy` | `dist/runtime-pin.json` (foundation build) | `"auto-minor"` | Controls how sites using this foundation receive runtime updates. Three values: `"exact"`, `"auto-patch"`, `"auto-minor"`. See "Foundation runtime policy" below. |
 
+**Catalog vs site-bound foundations.** Two distribution intents share the same `dist/foundation.js` artifact:
+
+- A **catalog foundation** is a deliberate product — named, versioned, listed in the catalog, consumable by other developers' sites. Use `uniweb publish @org/name` for these. The CLI requires an explicit name argument so you don't accidentally catalog a foundation that was meant to be site-bound.
+- A **site-bound foundation** powers exactly one site. Don't run `uniweb publish` for it. Just run `uniweb deploy` from the site directory — the CLI auto-publishes your local foundation as part of the deploy, under a registry slot scoped to the site itself, with no naming ceremony. The foundation isn't visible in the catalog and isn't owned by the developer who happened to run the deploy.
+
 **On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means renaming on the registry (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb publish --name marketing-pro` — it persists to `uniweb.id` without touching the workspace.
 
 These are the only fields the platform consumes today. Future platform features that need static configuration will land here too.

package/src/commands/build.js

@@ -1,33 +1,44 @@
 /**
  * Build Command
  *
- * Builds foundations with schema generation, or sites in either link or
- * bundle mode.
+ * Builds foundations with schema generation, or sites.
  *
- * Site build modes:
- *   --bundle (default for sites)
+ * Two site build pipelines are available, but they're INTERNAL vocabulary
+ * after Phase 2 of the CLI ergonomics overhaul. Users see `uniweb deploy`
+ * (uniweb-edge — runtime-linked) and `uniweb export` (third-party host —
+ * concatenated bundle); the build command itself just dispatches to whichever
+ * pipeline the caller requested.
+ *
+ *   --bundle (internal; called by `uniweb export`)
  *     Full vite + post-vite pipeline. Produces a static-host JS bundle
  *     (`dist/index.html`, `dist/entry.js`, `_importmap/*`, `_pages/*` for
  *     split mode, sitemap/robots/search-index, prerendered HTML when
- *     configured). Targets non-Uniweb hosts (Netlify, Vercel, GitHub
- *     Pages) and the future Uniweb bundled-mode hosting.
+ *     configured). Foundation is loaded by URL when site.yml's foundation
+ *     is a registry ref; statically inlined when it's a workspace-local
+ *     ref with no auto-publish (the narrow self-contained case).
  *
- *   --link
+ *   --link (internal; called by `uniweb deploy`)
  *     Data-only pipeline. No vite. Emits ONLY what the Uniweb-edge
  *     deploy needs: `dist/site-content.json` (with full sections),
  *     `dist/<lang>/site-content.json` per non-default locale,
  *     `dist/data/*.json` (collections), and `dist/assets/<media>` (images,
- *     fonts, video posters). Worker generates HTML at request time using
- *     its own runtime + the foundation served from the registry — the
- *     site's JS bundle is dead weight on this path.
+ *     fonts, video posters). Edge stitches runtime + foundation per
+ *     request — the site's JS bundle would be dead weight.
+ *
+ * Bare `uniweb build` for a site defaults to --bundle (the historical
+ * behavior). This is mostly useful for inspecting the build output during
+ * development; for shipping, use `uniweb deploy` or `uniweb export`.
  *
  * Usage:
  *   uniweb build                    # Build current directory (sites default to --bundle)
  *   uniweb build --target foundation # Explicitly build as foundation
  *   uniweb build --target site       # Explicitly build as site
- *   uniweb build --link              # Site: link-mode (data only, no vite)
- *   uniweb build --bundle            # Site: bundle-mode (full pipeline, today's behavior)
- *   uniweb build --prerender         # Bundle-mode site + SSG (static HTML)
+ *   uniweb build --prerender         # Force pre-rendering
+ *   uniweb build --no-prerender      # Skip pre-rendering
+ *
+ * Internal flags (called by `uniweb deploy` / `uniweb export`):
+ *   --link              # Data-only pipeline (Uniweb-edge)
+ *   --bundle            # Full vite pipeline (third-party hosts)
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -476,11 +487,11 @@ async function buildSiteLink(projectDir, options = {}) {
           success(`Translated collections for ${Object.keys(collectionOutputs).length} locale(s)`)
         }
       } catch (err) {
-        if (process.env.DEBUG) console.error('Collection translation:', err.message)
+        if (process.env.UNIWEB_DEBUG) console.error('Collection translation:', err.message)
       }
     } catch (err) {
       error(`i18n build failed: ${err.message}`)
-      if (process.env.DEBUG) console.error(err.stack)
+      if (process.env.UNIWEB_DEBUG) console.error(err.stack)
       log(`${colors.yellow}Continuing without localized content${colors.reset}`)
     }
   }
@@ -578,13 +589,13 @@ async function buildSite(projectDir, options = {}) {
         }
       } catch (err) {
         // Collection translation is optional, don't fail build
-        if (process.env.DEBUG) {
+        if (process.env.UNIWEB_DEBUG) {
           console.error('Collection translation:', err.message)
         }
       }
     } catch (err) {
       error(`i18n build failed: ${err.message}`)
-      if (process.env.DEBUG) {
+      if (process.env.UNIWEB_DEBUG) {
         console.error(err.stack)
       }
       // Don't fail the build, just warn
@@ -632,7 +643,7 @@ async function buildSite(projectDir, options = {}) {
         log(`  • The foundation's dist/foundation.js exists (build the foundation first)`)
       }
 
-      if (process.env.DEBUG) {
+      if (process.env.UNIWEB_DEBUG) {
         console.error(err.stack)
       }
       process.exit(1)
@@ -804,13 +815,12 @@ export async function build(args = []) {
   const prerenderFlag = args.includes('--prerender')
   const noPrerenderFlag = args.includes('--no-prerender')
 
-  // Check for --link / --bundle flags. These select between two
-  // mutually exclusive site build pipelines:
-  //   --link:   data only, no vite (for Uniweb-edge hosting)
-  //   --bundle: full vite pipeline (for static hosts; today's behavior)
-  // Bare `uniweb build` for a site defaults to --bundle for back-compat
-  // with users targeting static hosts. `uniweb deploy` always passes one
-  // of the two explicitly based on the resolved deploy mode.
+  // Internal flags — called by `uniweb deploy` (always --link) and
+  // `uniweb export` (always --bundle). After Phase 2 of the CLI
+  // ergonomics overhaul, users don't see these flags directly; they
+  // pick the deploy target (deploy vs export) and the corresponding
+  // pipeline runs. Bare `uniweb build` for a site defaults to --bundle
+  // (mostly used during development to inspect the vite output).
   const linkFlag = args.includes('--link')
   const bundleFlag = args.includes('--bundle')
   if (linkFlag && bundleFlag) {